@ziloen/micromark-extension-math 3.1.0-patch.0

package/dev/index.d.ts

@@ -0,0 +1,62 @@
+import type {KatexOptions} from 'katex'
+
+export {mathHtml} from './lib/html.js'
+export {math} from './lib/syntax.js'
+
+/**
+ * Configuration for HTML output.
+ *
+ * > 👉 **Note**: passed to `katex.renderToString`.
+ * > `displayMode` is overwritten by this plugin, to `false` for math in
+ * > text (inline), and `true` for math in flow (block).
+ */
+export interface HtmlOptions extends KatexOptions {
+  /**
+   * The field `displayMode` cannot be passed to `micromark-extension-math`.
+   * It is overwritten by it,
+   * to `false` for math in text (inline) and `true` for math in flow (block).
+   */
+  displayMode?: never
+}
+
+/**
+ * Configuration.
+ */
+export interface Options {
+  /**
+   * Whether to support math (text) with a single dollar (default: `true`).
+   *
+   * Single dollars work in Pandoc and many other places, but often interfere
+   * with “normal” dollars in text.
+   * If you turn this off, you can use two or more dollars for text math.
+   */
+  singleDollarTextMath?: boolean | null | undefined
+}
+
+/**
+ * Augment types.
+ */
+declare module 'micromark-util-types' {
+  /**
+   * Compile data.
+   */
+  interface CompileData {
+    mathFlowOpen?: boolean
+  }
+
+  /**
+   * Token types.
+   */
+  interface TokenTypeMap {
+    mathFlow: 'mathFlow'
+    mathFlowFence: 'mathFlowFence'
+    mathFlowFenceMeta: 'mathFlowFenceMeta'
+    mathFlowFenceSequence: 'mathFlowFenceSequence'
+    mathFlowValue: 'mathFlowValue'
+    mathText: 'mathText'
+    mathTextData: 'mathTextData'
+    mathTextDisplay: 'mathTextDisplay'
+    mathTextPadding: 'mathTextPadding'
+    mathTextSequence: 'mathTextSequence'
+  }
+}

package/dev/index.js

@@ -0,0 +1,3 @@
+// Note: types exported from `index.d.ts`.
+export {math} from './lib/syntax.js'
+export {mathHtml} from './lib/html.js'

package/dev/lib/html.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Create an extension for `micromark` to support math when serializing to
+ * HTML.
+ *
+ * > 👉 **Note**: this uses KaTeX to render math.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support math when serializing to HTML.
+ */
+export function mathHtml(options?: Options | null | undefined): HtmlExtension;
+import type { HtmlOptions as Options } from '@ziloen/micromark-extension-math';
+import type { HtmlExtension } from 'micromark-util-types';

package/dev/lib/html.js

@@ -0,0 +1,91 @@
+/**
+ * @import {HtmlOptions as Options} from '@ziloen/micromark-extension-math'
+ * @import {HtmlExtension} from 'micromark-util-types'
+ */
+
+import katex from 'katex'
+
+const renderToString = katex.renderToString
+
+/**
+ * Create an extension for `micromark` to support math when serializing to
+ * HTML.
+ *
+ * > 👉 **Note**: this uses KaTeX to render math.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support math when serializing to HTML.
+ */
+export function mathHtml(options) {
+  return {
+    enter: {
+      mathFlow() {
+        this.lineEndingIfNeeded()
+        this.tag('<div class="math math-display">')
+      },
+      mathFlowFenceMeta() {
+        this.buffer()
+      },
+      mathText() {
+        // Double?
+        this.tag('<span class="math math-inline">')
+        this.buffer()
+      },
+      mathTextDisplay() {
+        this.tag('<div class="math math-display">')
+        this.buffer()
+      }
+    },
+    exit: {
+      mathFlow() {
+        const value = this.resume()
+        this.tag(math(value.replace(/(?:\r?\n|\r)$/, ''), true))
+        this.tag('</div>')
+        this.setData('mathFlowOpen')
+        this.setData('slurpOneLineEnding')
+      },
+      mathFlowFence() {
+        // After the first fence.
+        if (!this.getData('mathFlowOpen')) {
+          this.setData('mathFlowOpen', true)
+          this.setData('slurpOneLineEnding', true)
+          this.buffer()
+        }
+      },
+      mathFlowFenceMeta() {
+        this.resume()
+      },
+      mathFlowValue(token) {
+        this.raw(this.sliceSerialize(token))
+      },
+      mathText() {
+        const value = this.resume()
+        this.tag(math(value, false))
+        this.tag('</span>')
+      },
+      mathTextDisplay() {
+        const value = this.resume()
+        this.tag(math(value, true))
+        this.tag('</div>')
+      },
+      mathTextData(token) {
+        this.raw(this.sliceSerialize(token))
+      }
+    }
+  }
+
+  /**
+   * @param {string} value
+   *   Math text.
+   * @param {boolean} displayMode
+   *   Whether the math is in display mode.
+   * @returns {string}
+   *   HTML.
+   */
+  function math(value, displayMode) {
+    return renderToString(value, {...options, displayMode})
+  }
+}

package/dev/lib/math-flow.d.ts

@@ -0,0 +1,3 @@
+/** @type {Construct} */
+export const mathFlow: Construct;
+import type { Construct } from 'micromark-util-types';

package/dev/lib/math-flow.js

@@ -0,0 +1,548 @@
+/**
+ * @import {Construct, State, TokenizeContext, Tokenizer} from 'micromark-util-types'
+ */
+
+import {ok as assert} from 'devlop'
+import {factorySpace} from 'micromark-factory-space'
+import {markdownLineEnding} from 'micromark-util-character'
+import {codes, constants, types} from 'micromark-util-symbol'
+
+/** @type {Construct} */
+export const mathFlow = {
+  tokenize: tokenizeMathFenced,
+  concrete: true,
+  name: 'mathFlow'
+}
+
+/** @type {Construct} */
+const nonLazyContinuation = {
+  tokenize: tokenizeNonLazyContinuation,
+  partial: true
+}
+
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
+function tokenizeMathFenced(effects, ok, nok) {
+  const self = this
+  const tail = self.events[self.events.length - 1]
+  const initialSize =
+    tail && tail[1].type === types.linePrefix
+      ? tail[2].sliceSerialize(tail[1], true).length
+      : 0
+  let sizeOpen = 0
+  let backslashContentSeen = false
+  let isBackslashMath = false
+
+  return start
+
+  /**
+   * Start of math.
+   *
+   * ```markdown
+   * > | $$
+   *     ^
+   *   | \frac{1}{2}
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function start(code) {
+    assert(
+      code === codes.dollarSign || code === codes.backslash,
+      'expected `$` or `\\`'
+    )
+    effects.enter('mathFlow')
+    effects.enter('mathFlowFence')
+    effects.enter('mathFlowFenceSequence')
+
+    if (code === codes.backslash) {
+      effects.consume(code)
+      return sequenceOpenBackslash
+    }
+
+    return sequenceOpen(code)
+  }
+
+  /**
+   * In opening fence sequence.
+   *
+   * ```markdown
+   * > | $$
+   *      ^
+   *   | \frac{1}{2}
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function sequenceOpen(code) {
+    if (code === codes.dollarSign) {
+      effects.consume(code)
+      sizeOpen++
+      return sequenceOpen
+    }
+
+    if (sizeOpen < 2) {
+      return nok(code)
+    }
+
+    effects.exit('mathFlowFenceSequence')
+    return factorySpace(effects, metaBefore, types.whitespace)(code)
+  }
+
+  /**
+   * After the backslash in an opening fence sequence.
+   *
+   * ```markdown
+   * > | \[
+   *      ^
+   *   | \frac{1}{2}
+   *   | \]
+   * ```
+   *
+   * @type {State}
+   */
+  function sequenceOpenBackslash(code) {
+    if (code !== codes.leftSquareBracket) {
+      return nok(code)
+    }
+
+    isBackslashMath = true
+    effects.consume(code)
+    effects.exit('mathFlowFenceSequence')
+    effects.exit('mathFlowFence')
+
+    if (self.interrupt) {
+      return ok
+    }
+
+    return backslashContentStart
+  }
+
+  /**
+   * In opening fence, before meta.
+   *
+   * ```markdown
+   * > | $$asciimath
+   *       ^
+   *   | x < y
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+
+  function metaBefore(code) {
+    if (code === codes.eof || markdownLineEnding(code)) {
+      return metaAfter(code)
+    }
+
+    effects.enter('mathFlowFenceMeta')
+    effects.enter(types.chunkString, {contentType: constants.contentTypeString})
+    return meta(code)
+  }
+
+  /**
+   * In meta.
+   *
+   * ```markdown
+   * > | $$asciimath
+   *        ^
+   *   | x < y
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function meta(code) {
+    if (code === codes.eof || markdownLineEnding(code)) {
+      effects.exit(types.chunkString)
+      effects.exit('mathFlowFenceMeta')
+      return metaAfter(code)
+    }
+
+    if (code === codes.dollarSign) {
+      return nok(code)
+    }
+
+    effects.consume(code)
+    return meta
+  }
+
+  /**
+   * After meta.
+   *
+   * ```markdown
+   * > | $$
+   *       ^
+   *   | \frac{1}{2}
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function metaAfter(code) {
+    // Guaranteed to be eol/eof.
+    effects.exit('mathFlowFence')
+
+    if (self.interrupt) {
+      return ok(code)
+    }
+
+    return effects.attempt(
+      nonLazyContinuation,
+      beforeNonLazyContinuation,
+      after
+    )(code)
+  }
+
+  /**
+   * After eol/eof in math, at a non-lazy closing fence or content.
+   *
+   * ```markdown
+   *   | $$
+   * > | \frac{1}{2}
+   *     ^
+   * > | $$
+   *     ^
+   * ```
+   *
+   * @type {State}
+   */
+  function beforeNonLazyContinuation(code) {
+    return effects.attempt(
+      {tokenize: tokenizeClosingFence, partial: true},
+      after,
+      contentStart
+    )(code)
+  }
+
+  /**
+   * Before math content, definitely not before a closing fence.
+   *
+   * ```markdown
+   *   | $$
+   * > | \frac{1}{2}
+   *     ^
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function contentStart(code) {
+    return (
+      initialSize
+        ? factorySpace(
+            effects,
+            beforeContentChunk,
+            types.linePrefix,
+            initialSize + 1
+          )
+        : beforeContentChunk
+    )(code)
+  }
+
+  /**
+   * Before math content, after optional prefix.
+   *
+   * ```markdown
+   *   | $$
+   * > | \frac{1}{2}
+   *     ^
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function beforeContentChunk(code) {
+    if (code === codes.eof) {
+      return after(code)
+    }
+
+    if (markdownLineEnding(code)) {
+      return effects.attempt(
+        nonLazyContinuation,
+        beforeNonLazyContinuation,
+        after
+      )(code)
+    }
+
+    effects.enter('mathFlowValue')
+    return contentChunk(code)
+  }
+
+  /**
+   * In math content.
+   *
+   * ```markdown
+   *   | $$
+   * > | \frac{1}{2}
+   *      ^
+   *   | $$
+   * ```
+   *
+   * @type {State}
+   */
+  function contentChunk(code) {
+    if (code === codes.eof || markdownLineEnding(code)) {
+      effects.exit('mathFlowValue')
+      return beforeContentChunk(code)
+    }
+
+    effects.consume(code)
+    return contentChunk
+  }
+
+  /**
+   * After math (ha!).
+   *
+   * ```markdown
+   *   | $$
+   *   | \frac{1}{2}
+   * > | $$
+   *       ^
+   * ```
+   *
+   * @type {State}
+   */
+  function after(code) {
+    if (isBackslashMath && !backslashContentSeen) {
+      return nok(code)
+    }
+
+    effects.exit('mathFlow')
+    return ok(code)
+  }
+
+  /**
+   * Before math content or a closing backslash fence.
+   *
+   * @type {State}
+   */
+  function backslashContentStart(code) {
+    return effects.attempt(
+      {tokenize: tokenizeClosingBackslashFence, partial: true},
+      after,
+      backslashBeforeContentChunk
+    )(code)
+  }
+
+  /**
+   * Before math content, definitely not before a closing backslash fence.
+   *
+   * @type {State}
+   */
+  function backslashBeforeContentChunk(code) {
+    if (code === codes.eof) {
+      return after(code)
+    }
+
+    if (markdownLineEnding(code)) {
+      return effects.attempt(
+        nonLazyContinuation,
+        backslashContentStart,
+        after
+      )(code)
+    }
+
+    if (code === codes.backslash) {
+      effects.enter('mathFlowValue')
+      effects.consume(code)
+      backslashContentSeen = true
+      effects.exit('mathFlowValue')
+      return backslashBeforeContentChunk
+    }
+
+    effects.enter('mathFlowValue')
+    return backslashContentChunk(code)
+  }
+
+  /**
+   * In backslash-delimited math content.
+   *
+   * @type {State}
+   */
+  function backslashContentChunk(code) {
+    if (code === codes.eof || markdownLineEnding(code)) {
+      effects.exit('mathFlowValue')
+      return backslashBeforeContentChunk(code)
+    }
+
+    if (code === codes.backslash) {
+      effects.exit('mathFlowValue')
+      return backslashContentStart(code)
+    }
+
+    effects.consume(code)
+    backslashContentSeen = true
+    return backslashContentChunk
+  }
+
+  /** @type {Tokenizer} */
+  function tokenizeClosingFence(effects, ok, nok) {
+    let size = 0
+
+    assert(self.parser.constructs.disable.null, 'expected `disable.null`')
+    /**
+     * Before closing fence, at optional whitespace.
+     *
+     * ```markdown
+     *   | $$
+     *   | \frac{1}{2}
+     * > | $$
+     *     ^
+     * ```
+     */
+    return factorySpace(
+      effects,
+      beforeSequenceClose,
+      types.linePrefix,
+      self.parser.constructs.disable.null.includes('codeIndented')
+        ? undefined
+        : constants.tabSize
+    )
+
+    /**
+     * In closing fence, after optional whitespace, at sequence.
+     *
+     * ```markdown
+     *   | $$
+     *   | \frac{1}{2}
+     * > | $$
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+    function beforeSequenceClose(code) {
+      effects.enter('mathFlowFence')
+      effects.enter('mathFlowFenceSequence')
+      return sequenceClose(code)
+    }
+
+    /**
+     * In closing fence sequence.
+     *
+     * ```markdown
+     *   | $$
+     *   | \frac{1}{2}
+     * > | $$
+     *      ^
+     * ```
+     *
+     * @type {State}
+     */
+    function sequenceClose(code) {
+      if (code === codes.dollarSign) {
+        size++
+        effects.consume(code)
+        return sequenceClose
+      }
+
+      if (size < sizeOpen) {
+        return nok(code)
+      }
+
+      effects.exit('mathFlowFenceSequence')
+      return factorySpace(effects, afterSequenceClose, types.whitespace)(code)
+    }
+
+    /**
+     * After closing fence sequence, after optional whitespace.
+     *
+     * ```markdown
+     *   | $$
+     *   | \frac{1}{2}
+     * > | $$
+     *       ^
+     * ```
+     *
+     * @type {State}
+     */
+    function afterSequenceClose(code) {
+      if (code === codes.eof || markdownLineEnding(code)) {
+        effects.exit('mathFlowFence')
+        return ok(code)
+      }
+
+      return nok(code)
+    }
+  }
+
+  /** @type {Tokenizer} */
+  function tokenizeClosingBackslashFence(effects, ok, nok) {
+    return beforeSequenceClose
+
+    /**
+     * In closing fence sequence.
+     *
+     * @type {State}
+     */
+    function beforeSequenceClose(code) {
+      if (code !== codes.backslash) {
+        return nok(code)
+      }
+
+      effects.enter('mathFlowFence')
+      effects.enter('mathFlowFenceSequence')
+      effects.consume(code)
+      return sequenceClose
+    }
+
+    /**
+     * After the backslash in a closing fence sequence.
+     *
+     * @type {State}
+     */
+    function sequenceClose(code) {
+      if (code !== codes.rightSquareBracket) {
+        return nok(code)
+      }
+
+      effects.consume(code)
+      effects.exit('mathFlowFenceSequence')
+      return factorySpace(effects, afterSequenceClose, types.whitespace)
+    }
+
+    /**
+     * After closing fence sequence, after optional whitespace.
+     *
+     * @type {State}
+     */
+    function afterSequenceClose(code) {
+      effects.exit('mathFlowFence')
+      return ok(code)
+    }
+  }
+}
+
+/**
+ * @this {TokenizeContext}
+ * @type {Tokenizer}
+ */
+function tokenizeNonLazyContinuation(effects, ok, nok) {
+  const self = this
+
+  return start
+
+  /** @type {State} */
+  function start(code) {
+    if (code === null) {
+      return ok(code)
+    }
+
+    assert(markdownLineEnding(code), 'expected eol')
+    effects.enter(types.lineEnding)
+    effects.consume(code)
+    effects.exit(types.lineEnding)
+    return lineStart
+  }
+
+  /** @type {State} */
+  function lineStart(code) {
+    return self.parser.lazy[self.now().line] ? nok(code) : ok(code)
+  }
+}