✨ Colon fence renderer (#39)

Author: rowanc1

package-lock.json

@@ -59,6 +59,7 @@
   "devDependencies": {
     "@rollup/plugin-babel": "^5.3.0",
     "@rollup/plugin-commonjs": "^21.0.1",
+    "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.1.3",
     "@types/jest": "^27.4.0",
     "@types/js-yaml": "^4.0.5",

package.json

@@ -3,14 +3,16 @@ import commonjs from "@rollup/plugin-commonjs"
 import babel from "@rollup/plugin-babel"
 import resolve from "@rollup/plugin-node-resolve"
 import { terser } from "rollup-plugin-terser"
+import json from "@rollup/plugin-json"
 
 export default {
   input: "src/index.ts",
   plugins: [
     typescript(), // Integration between Rollup and Typescript
     commonjs(), // Convert CommonJS modules to ES6
     babel({ babelHelpers: "bundled" }), // transpile ES6/7 code
-    resolve() // resolve third party modules in node_modules
+    resolve(), // resolve third party modules in node_modules
+    json()
   ],
   output: [
     {

rollup.config.js

@@ -0,0 +1,137 @@
+import type MarkdownIt from "markdown-it/lib"
+import type Renderer from "markdown-it/lib/renderer"
+import type StateBlock from "markdown-it/lib/rules_block/state_block"
+import { escapeHtml, unescapeAll } from "markdown-it/lib/common/utils"
+
+// Ported from: https://github.com/executablebooks/mdit-py-plugins/blob/master/mdit_py_plugins/colon_fence.py
+
+function _rule(state: StateBlock, startLine: number, endLine: number, silent: boolean) {
+  let haveEndMarker = false
+  let pos = state.bMarks[startLine] + state.tShift[startLine]
+  let maximum = state.eMarks[startLine]
+
+  // if it's indented more than 3 spaces, it should be a code block
+  if (state.sCount[startLine] - state.blkIndent >= 4) {
+    return false
+  }
+
+  if (pos + 3 > maximum) {
+    return false
+  }
+
+  const marker = state.src.charCodeAt(pos)
+
+  // /* : */
+  if (marker !== 0x3a) {
+    return false
+  }
+
+  // scan marker length
+  let mem = pos
+  pos = state.skipChars(pos, marker)
+
+  let length = pos - mem
+
+  if (length < 3) {
+    return false
+  }
+
+  const markup = state.src.slice(mem, pos)
+  const params = state.src.slice(pos, maximum)
+
+  // Since start is found, we can report success here in validation mode
+  if (silent) {
+    return true
+  }
+
+  // search end of block
+  let nextLine = startLine
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    nextLine += 1
+    if (nextLine >= endLine) {
+      // unclosed block should be autoclosed by end of document.
+      // also block seems to be autoclosed by end of parent
+      break
+    }
+
+    pos = mem = state.bMarks[nextLine] + state.tShift[nextLine]
+    maximum = state.eMarks[nextLine]
+
+    if (pos < maximum && state.sCount[nextLine] < state.blkIndent) {
+      // non-empty line with negative indent should stop the list:
+      // - ```
+      //  test
+      break
+    }
+
+    if (state.src.charCodeAt(pos) != marker) {
+      continue
+    }
+
+    if (state.sCount[nextLine] - state.blkIndent >= 4) {
+      // closing fence should be indented less than 4 spaces
+      continue
+    }
+
+    pos = state.skipChars(pos, marker)
+
+    // closing code fence must be at least as long as the opening one
+    if (pos - mem < length) {
+      continue
+    }
+
+    // make sure tail has spaces only
+    pos = state.skipSpaces(pos)
+
+    if (pos < maximum) {
+      continue
+    }
+
+    haveEndMarker = true
+    // found!
+    break
+  }
+  // If a fence has heading spaces, they should be removed from its inner block
+  length = state.sCount[startLine]
+
+  state.line = nextLine + (haveEndMarker ? 1 : 0)
+
+  const token = state.push("colon_fence", "code", 0)
+  token.info = params
+  token.content = state.getLines(startLine + 1, nextLine, length, true)
+  token.markup = markup
+  token.map = [startLine, state.line]
+
+  return true
+}
+
+const colonFenceRender: Renderer.RenderRule = function colonFenceRender(tokens, idx) {
+  const token = tokens[idx]
+  const info = token.info ? unescapeAll(token.info).trim() : ""
+  const content = escapeHtml(token.content)
+  let block_name = ""
+
+  if (info) {
+    block_name = info.split(" ")[0]
+  }
+  const codeClass = block_name ? ` class="block-${block_name}"` : ""
+  return `<pre><code${codeClass}>${content}</code></pre>\n`
+}
+
+/**
+ * This plugin directly mimics regular fences, but with `:` colons.
+ * Example:
+ * ```md
+ * :::name
+ * contained text
+ * :::
+ * ```
+ */
+export function colonFencePlugin(md: MarkdownIt) {
+  md.block.ruler.before("fence", "colon_fence", _rule, {
+    alt: ["paragraph", "reference", "blockquote", "list", "footnote_def"]
+  })
+  md.renderer.rules["colon_fence"] = colonFenceRender
+}

src/colonFence.ts

@@ -29,7 +29,7 @@ export default function directivePlugin(md: MarkdownIt, options: IOptions): void
 /** Convert fences identified as directives to `directive` tokens */
 function replaceFences(state: StateCore): boolean {
   for (const token of state.tokens) {
-    if (token.type === "fence") {
+    if (token.type === "fence" || token.type === "colon_fence") {
       const match = token.info.match(/^\{([^\s}]+)\}\s*(.*)$/)
       if (match) {
         token.type = "directive"

src/directives/plugin.ts

@@ -9,6 +9,7 @@ import {
   IDirectiveData
 } from "./directives"
 import statePlugin from "./state/plugin"
+import { colonFencePlugin } from "./colonFence"
 
 export { rolesDefault, rolePlugin, Role }
 export { directivesDefault, directivePlugin, Directive, directiveOptions }
@@ -18,11 +19,13 @@ export type { IRoleData, IRoleOptions, IDirectiveData, IDirectiveOptions }
 /** Allowed options for docutils plugin */
 export interface IOptions extends IDirectiveOptions, IRoleOptions {
   // TODO new token render rules
+  colonFences: boolean
 }
 
 /** Default options for docutils plugin */
 const OptionDefaults: IOptions = {
   parseRoles: true,
+  colonFences: true,
   replaceFences: true,
   rolesAfter: "inline",
   directivesAfter: "block",
@@ -36,6 +39,7 @@ const OptionDefaults: IOptions = {
 export function docutilsPlugin(md: MarkdownIt, options?: IOptions): void {
   const fullOptions = { ...OptionDefaults, ...options }
 
+  if (fullOptions.colonFences) md.use(colonFencePlugin)
   md.use(rolePlugin, fullOptions)
   md.use(directivePlugin, fullOptions)
   md.use(statePlugin, fullOptions)

src/index.ts

@@ -0,0 +1,27 @@
+/* eslint-disable jest/valid-title */
+import MarkdownIt from "markdown-it"
+import docutils_plugin from "../src"
+import readFixtures from "./readFixtures"
+
+describe("Parses colonFences", () => {
+  test("colon fences parse", () => {
+    const mdit = MarkdownIt().use(docutils_plugin)
+    const parse = mdit.parse(`:::{tip}\nThis is a tip in a fence!\n:::`, {})
+    expect(parse[0].type).toBe("parsed_directive_open")
+  })
+  test("colon fences render", () => {
+    const mdit = MarkdownIt().use(docutils_plugin)
+    const rendered = mdit.render(`:::{tip}\nfence\n:::`)
+    expect(rendered.trim()).toEqual(
+      '<aside class="admonition tip">\n<header class="admonition-title">Tip</header>\n<p>fence</p>\n</aside>'
+    )
+  })
+})
+
+describe("Parses fenced directives", () => {
+  readFixtures("directives.fence").forEach(([name, text, expected]) => {
+    const mdit = MarkdownIt().use(docutils_plugin)
+    const rendered = mdit.render(text)
+    it(name, () => expect(rendered.trim()).toEqual((expected || "").trim()))
+  })
+})

tests/colonFences.spec.ts

@@ -0,0 +1,36 @@
+Unknown fence directive
+.
+:::{unknown} argument
+content
+:::
+.
+<aside class="directive-unhandled">
+<header><mark>unknown</mark><code> argument</code></header>
+<pre>content
+</pre></aside>
+.
+
+Fenced admonition:
+.
+:::{admonition} This is a **title**
+An example of an admonition with custom _title_.
+:::
+.
+<aside class="admonition">
+<header class="admonition-title">This is a <strong>title</strong></header>
+<p>An example of an admonition with custom <em>title</em>.</p>
+</aside>
+.
+
+Fenced note on split lines:
+.
+:::{note} An example
+of an admonition on two lines.
+:::
+.
+<aside class="admonition note">
+<header class="admonition-title">Note</header>
+<p>An example
+of an admonition on two lines.</p>
+</aside>
+.