👌 IMPROVE: Add parsed_directive and parsed_role parent tokens (#34)

In order to not lose the information, of what nodes were generated from directives/roles,
these nodes are now wrapped inside `parsed_directive` and `parsed_role` parent tokens,
e.g. 

```xml
<admonition class="note" ...>
  ...
```

will now be output as:

```xml
<parsed_directive name="note" ...>
  <admonition class="note" ...>
    ...
```

Additionally, `legend` tokens for paragraphs have been added,
after `caption` in figure directives.

Author: fwkoch

src/directives/images.ts

@@ -121,7 +121,11 @@ export class Figure extends Image {
     const imageToken = this.create_image(data)
     imageToken.map = [data.map[0], data.map[0]]
     let captionTokens: Token[] = []
+    let legendTokens: Token[] = []
     if (data.body) {
+      const [caption, ...legendParts] = data.body.split("\n\n")
+      const legend = legendParts.join("\n\n")
+      const captionMap = data.bodyMap[0]
       const openCaption = this.createToken("figure_caption_open", "figcaption", 1, {
         block: true
       })
@@ -130,14 +134,25 @@ export class Figure extends Image {
       }
       // TODO in docutils caption can only be single paragraph (or ignored if comment)
       // then additional content is figure legend
-      const captionBody = this.nestedParse(data.body, data.bodyMap[0])
+      const captionBody = this.nestedParse(caption, captionMap)
       const closeCaption = this.createToken("figure_caption_close", "figcaption", -1, {
         block: true
       })
       captionTokens = [openCaption, ...captionBody, closeCaption]
+      if (legend) {
+        const legendMap = captionMap + caption.split("\n").length + 1
+        const openLegend = this.createToken("figure_legend_open", "", 1, {
+          block: true
+        })
+        const legendBody = this.nestedParse(legend, legendMap)
+        const closeLegend = this.createToken("figure_legend_close", "", -1, {
+          block: true
+        })
+        legendTokens = [openLegend, ...legendBody, closeLegend]
+      }
     }
     const closeToken = this.createToken("figure_close", "figure", -1, { block: true })
-    return [openToken, imageToken, ...captionTokens, closeToken]
+    return [openToken, imageToken, ...captionTokens, ...legendTokens, closeToken]
   }
 }
 

src/directives/main.ts

@@ -213,7 +213,7 @@ export default function directiveToData(
   }
 }
 
-function parseDirectiveOptions(
+export function parseDirectiveOptions(
   content: string[],
   fullSpec: IDirectiveSpec
 ): [string[], { [key: string]: any }, number] {

src/directives/plugin.ts

@@ -1,6 +1,6 @@
 import type MarkdownIt from "markdown-it/lib"
 import type StateCore from "markdown-it/lib/rules_core/state_core"
-import directiveToData, { Directive } from "./main"
+import directiveToData, { Directive, parseDirectiveOptions } from "./main"
 import { IOptions } from "./types"
 
 export default function directivePlugin(md: MarkdownIt, options: IOptions): void {
@@ -53,12 +53,28 @@ function runDirectives(directives: {
         try {
           const directive = new directives[token.info](state)
           const data = directiveToData(token, directive)
-          const newTokens = directive.run(data)
-          // Ensure `meta` exists and add the directive options
-          newTokens[0].meta = {
+          const [content, opts] = parseDirectiveOptions(
+            token.content.trim() ? token.content.split(/\r?\n/) : [],
+            directive
+          )
+          const directiveOpen = new state.Token("parsed_directive_open", "", 1)
+          directiveOpen.info = token.info
+          directiveOpen.hidden = true
+          directiveOpen.content = content.join("\n").trim()
+          directiveOpen.meta = {
+            arg: token.meta.arg,
+            opts
+          }
+          const newTokens = [directiveOpen]
+          newTokens.push(...directive.run(data))
+          const directiveClose = new state.Token("parsed_directive_close", "", -1)
+          directiveClose.hidden = true
+          newTokens.push(directiveClose)
+          // Ensure `meta` exists and add the directive options to parsed child
+          newTokens[1].meta = {
             directive: true,
             ...data.options,
-            ...newTokens[0].meta
+            ...newTokens[1].meta
           }
           finalTokens.push(...newTokens)
         } catch (err) {

src/roles/plugin.ts

@@ -52,6 +52,7 @@ function roleRule(state: StateInline, silent: boolean): boolean {
 }
 
 // MyST role syntax format e.g. {role}`text`
+// TODO: support role with no value e.g. {role}``
 let _x: RegExp
 try {
   _x = new RegExp("^\\{([a-zA-Z_\\-+:]{1,36})\\}(`+)(?!`)(.+?)(?<!`)\\2(?!`)")
@@ -75,10 +76,22 @@ function runRoles(roles: {
           if (child.type === "role" && child.meta?.name in roles) {
             try {
               const role = new roles[child.meta.name](state)
-              const newTokens = role.run({
-                parentMap: token.map,
-                content: child.content
-              })
+              const roleOpen = new state.Token("parsed_role_open", "", 1)
+              roleOpen.content = child.content
+              roleOpen.hidden = true
+              roleOpen.meta = { name: child.meta.name }
+              roleOpen.block = false
+              const newTokens = [roleOpen]
+              newTokens.push(
+                ...role.run({
+                  parentMap: token.map,
+                  content: child.content
+                })
+              )
+              const roleClose = new state.Token("parsed_role_close", "", -1)
+              roleClose.block = false
+              roleClose.hidden = true
+              newTokens.push(roleClose)
               childTokens.push(...newTokens)
             } catch (err) {
               const errorToken = new state.Token("role_error", "", 0)

tests/fixtures/directives.admonitions.md

@@ -57,6 +57,7 @@ nested-admonition
 <aside class="admonition note">
 <header class="admonition-title">Note</header>
 <p>This is a note</p>
+
 <aside class="admonition warning">
 <header class="admonition-title">Warning</header>
 <p>This is a nested warning</p>

tests/fixtures/roles.references.eq.md

@@ -9,5 +9,6 @@ Check out {eq}`my_label`!
 <div class="math block" id="my_label" number="1">
 w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
 </div>
+
 <p>Check out <a href="#my_label">(1)</a>!</p>
 .

tests/fixtures/roles.references.numref.md

@@ -30,12 +30,14 @@ The reference to {ref}`test3` and {ref}`test4`.
 <p>Fig 1</p>
 </figcaption>
 </figure>
+
 <figure id="test4" class="numbered">
 <img src="https://via.placeholder.com/150" alt="">
 <figcaption number="2">
 <p>Fig 2</p>
 </figcaption>
 </figure>
+
 <p>The reference to <a href="#test3" title="Fig 1">Fig 1</a> and <a href="#test4" title="Fig 2">Fig 2</a>.
 <a href="#test3" title="Fig 1">Fig 1</a>
 <a href="#test4" title="Fig 2">Fig 2</a>