Trouble with children in custom "admonition" plugin in compiler

[Firgrep]

Hi there,

I'm having some issues with passing children in a plugin made for directives. I'm using MDX Editor to write the mdx, which, upon hitting a save button, sends the mdx string to the compiler.

I've almost got it working but in order for the admonition to appear as it does in the MDX Editor, I need to insert an additional <div> between the directive <div> and the contents. I want to keep the contents as they are since there may be a lot of different things coming in, and so I try to just pass the node.children as the children of this new child.

So basically, all I want to do is to insert a new <div> between the directive's <div> and its children.

But when I pass the node.children into the h() function, the compilation doesn't complete (I get an error thrown in the function that calls the compiler). However, if I pass a string as children into the h(), then everything works fine.

Here is the compiler, the plugin, and the mdx source.

import {compile} from '@mdx-js/mdx'
import remarkGfm from "remark-gfm";
import remarkDirective from 'remark-directive';

export const mdxCompiler = async (mdxSource: string) => {
    try {
        const mdxCompiled = String(await compile(mdxSource, {
            outputFormat: 'function-body',
            development: false,
            remarkPlugins: [remarkGfm, remarkDirective, adminitionPlugin],
        }));
        console.log("COMPILED: \n", mdxCompiled) // this line does not get hit
        return mdxCompiled;
    } catch(e) {
        throw new Error("An error occured in the mdxCompiler");
    }
}

import {h} from 'hastscript'
import {visit} from 'unist-util-visit'

const ADMONITION_TYPES = ["note", "tip", "danger", "info", "caution"]
function adminitionPlugin() {
    // @ts-ignore
    return (tree) => {
        visit(tree, (node) => {
            if (
                node.type === 'containerDirective' ||
                node.type === 'leafDirective' ||
                node.type === 'textDirective'
            ) {
                if (ADMONITION_TYPES.includes(node.name)) {

                    const data = node.data || (node.data = {});
                    const tagName = node.type === 'textDirective' ? 'span' : 'div';
                    
                    if (node.name === ADMONITION_TYPES[0]) {
                        node.attributes = {
                            ...node.attributes,
                            class: '_admonitionNote_13nbk_63', 
                        };
                    } else if (node.name === ADMONITION_TYPES[1]) {
                        node.attributes = {
                            ...node.attributes,
                            class: '_admonitionTip_13nbk_63', 
                        };
                    } else if (node.name === ADMONITION_TYPES[2]) {
                        node.attributes = {
                            ...node.attributes,
                            class: '_admonitionDanger_13nbk_63', 
                        };
                    } else if (node.name === ADMONITION_TYPES[3]) {
                        node.attributes = {
                            ...node.attributes,
                            class: '_admonitionInfo_13nbk_63', 
                        };
                    } else if (node.name === ADMONITION_TYPES[4]) {
                        node.attributes = {
                            ...node.attributes,
                            class: '_admonitionCaution_13nbk_63', 
                        };
                    }
                    
                    data.hName = tagName;
                    data.hProperties = h(tagName, node.attributes || {}).properties;
                    console.log("NODE CHILDREN: \n", node.children)
                    // inserting new child to node.data and passing node.data's children to this new child
                    data.hChildren = [
                        h('div', {class: "_nestedEditor_w1wlt_891"}, node.children) 
                                // if i swap node.children here with a string, the compilation runs fine
                    ];
                    console.log("DATA: \n", data)
                    console.log("old children under new child of node.data: \n", data.hChildren[0].children)
                }
            }
        })
    }
}

The mdx source:

# Supercool big title

:::danger
danger multi-line admonition

here is the second line

and third
:::

last sentence

Logs from the console:

// this is prior the h() function being called, and so these are the children of the directive
NODE CHILDREN:
 [
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  },
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  },
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  }
]

// this is after the h() function is called, so the directive gets a new class attribute as well as
// a new child div, which itself is supposed to take over its children
DATA:
 {
  hName: 'div',
  hProperties: { className: [ '_admonitionDanger_13nbk_63' ] },
  hChildren: [
    {
      type: 'element',
      tagName: 'div',
      properties: [Object],
      children: [Array]
    }
  ]
}

// inspecting the transfered children, it appears just as it was in the first console log
// which is expected
old children under new child of node.data:
 [
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  },
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  },
  {
    type: 'paragraph',
    children: [ [Object] ],
    position: { start: [Object], end: [Object] }
  }
]

So I'm really not sure what's going here. Thanks for any help!

[ChristianMurphy]

Welcome @Firgrep! 👋
Sorry you ran into a spot of trouble.
This looks very similar to https://github.com/orgs/remarkjs/discussions/1218
The issue you are facing is the hChildren prop accepts an HTML AST (hast), but you are passing a Markdown AST (mdast). https://github.com/syntax-tree/mdast-util-to-hast#hchildren

The easier approach to solve this would be to use plain children prop instead which does accept mdast.

[Firgrep]

I couldn't get the Node.js box to work, so I try with create-react-app, and even though I'm getting React errors, you can see the compiler's output in the browser console. It appears the same as on my local app: the new div is missing.

https://stackblitz.com/edit/github-qo53wd?file=src%2FApp.js

[ChristianMurphy]

@Firgrep thanks for sharing, is not with MDX, it is that React does not support async hooks.
Some commentary on that here: https://ultimatecourses.com/blog/using-async-await-inside-react-use-effect-hook

A working example would be: https://stackblitz.com/edit/github-qo53wd-ati5ag?file=src%2FApp.js

source from example

import { useEffect, useState } from 'react';
import * as runtime from 'react/jsx-runtime';
import { evaluate } from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import remarkDirective from 'remark-directive';
import { visit } from 'unist-util-visit';
const ADMONITION_TYPES = ['note', 'tip', 'danger', 'info', 'caution'];

function adminitionPlugin() {
  return (tree) => {
    visit(tree, (node) => {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        if (ADMONITION_TYPES.includes(node.name)) {
          const data = node.data || (node.data = {});
          const tagName = node.type === 'textDirective' ? 'span' : 'div';

          if (node.name === ADMONITION_TYPES[0]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionNote_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[1]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionTip_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[2]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionDanger_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[3]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionInfo_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[4]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionCaution_13nbk_63',
            };
          }

          data.hName = tagName;
          data.hProperties = node.attributes;
          console.log('NODE CHILDREN: \n', node.children);

          data.children = [
            {
              type: 'paragraph',
              hName: 'div',
              hProperties: { className: ['_nestedEditor_w1wlt_891'] },
              children: node.children,
            },
          ];

          console.log('DATA: \n', data);
          console.log(
            'old children under new child of node.data: \n',
            node.children
          );
        }
      }
    });
  };
}

const mdxContent = `
# Supercool big title

:::danger
danger multi-line admonition

here is the second line

and third
:::

last sentence
`;

export function useMDX(mdxSource) {
  const [component, setComponent] = useState('div');
  useEffect(() => {
    const render = async () => {
      try {
        const { default: Content } = await evaluate(mdxSource, {
          ...runtime,
          ...{ remarkPlugins: [remarkGfm, remarkDirective, adminitionPlugin] },
          development: false,
        });
        console.log('component', Content);
        setComponent(Content);
      } catch (e) {
        throw new Error('An error occured in the mdxCompiler');
      }
    };

    render();
  }, [mdxSource]);
  console.log('component', component);
  return component;
}

export default function App() {
  const Component = useMDX(mdxContent);
  return Component;
}

[Firgrep]

@ChristianMurphy thanks for cleaning that up and making a working example. I'll have a look at the commentary about async and React!

Have you had any further ideas about the div insertion? I notice that in the working sample, if I add an empty array to node.children, the children still appear to render. If change it to, node.hChildren they do not render (as expected from an empty array).

[ChristianMurphy]

Focus on the distinction between what properties can be applied directly to node and which go on node.data
children is a property directly of node.
hProperties and hName are of node.data.
ref: https://github.com/syntax-tree/mdast#readme and https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes

Those were flipped in a few spots causing bugs.
I'd highly recommend using TypeScript or JSDoc (with TypeScript validation) to help catch mismatch in object structures.
With the data put in the correct spot, it adds the elements as expected:

https://stackblitz.com/edit/github-qo53wd-7vuhzr?file=src%2FApp.js

source from sandbox

import { useEffect, useState } from 'react';
import * as runtime from 'react/jsx-runtime';
import { evaluate } from '@mdx-js/mdx';
import remarkGfm from 'remark-gfm';
import remarkDirective from 'remark-directive';
import { visit } from 'unist-util-visit';
const ADMONITION_TYPES = ['note', 'tip', 'danger', 'info', 'caution'];

function adminitionPlugin() {
  return (tree) => {
    visit(tree, (node) => {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        if (ADMONITION_TYPES.includes(node.name)) {
          node.data = node.data ?? {};
          const tagName = node.type === 'textDirective' ? 'span' : 'div';

          if (node.name === ADMONITION_TYPES[0]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionNote_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[1]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionTip_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[2]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionDanger_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[3]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionInfo_13nbk_63',
            };
          } else if (node.name === ADMONITION_TYPES[4]) {
            node.attributes = {
              ...node.attributes,
              className: '_admonitionCaution_13nbk_63',
            };
          }

          node.type = 'paragraph';
          node.data = {
            ...node.data,
            hName: tagName,
            hProperties: node.attributes,
          };

          node.children = [
            {
              type: 'paragraph',
              data: {
                hName: 'div',
                hProperties: { className: ['_nestedEditor_w1wlt_891'] },
              },
              children: node.children,
            },
          ];
        }
      }
    });
  };
}

const mdxContent = `
# Supercool big title

:::danger
danger multi-line admonition

here is the second line

and third
:::

last sentence
`;

export function useMDX(mdxSource) {
  const [component, setComponent] = useState('div');
  useEffect(() => {
    const render = async () => {
      try {
        const { default: Content } = await evaluate(mdxSource, {
          ...runtime,
          ...{ remarkPlugins: [remarkGfm, remarkDirective, adminitionPlugin] },
          development: false,
        });
        setComponent(Content);
      } catch (e) {
        throw new Error('An error occured in the mdxCompiler');
      }
    };

    render();
  }, [mdxSource]);
  return component;
}

export default function App() {
  const Component = useMDX(mdxContent);
  return Component;
}

[Firgrep]

@ChristianMurphy OK, I've kept tinkering with it and I think I've maybe got something. I had a look at the mdx playground and looked at what the mdast produced when I put a <div></div> into the mdx. I also removed any hStuff just in case that was confusing the compiler, and after that node.children reacted as expected. I've afterwards re-instated the hastscript stuff related to the top-parent div in order to change the attributes.

I want to check and see if I can get this working on my local app, but this is promising!

https://stackblitz.com/edit/github-qo53wd-nvcbw5?file=src%2FApp.js

Main change/addition

```ts node.children = [ { type: "mdxJsxFlowElement", name: "div", attributes: [ { type: "mdxJsxAttribute", name: "class", value: "inner_admonition_class_thing" } ], children: node.children, } ] ```

[Firgrep]

@ChristianMurphy Sorry, missed your latest reply! Ah, I see how I've not really had a clear grasp of node and node.data. I'm looking at your example now and it's very helpful. I think that should sort my problem!

Yes, I do use TypeScript on my local app, but I had its typechecking switched off for the admonition function after it was complaining that the type i added for tree was excessively large or possibly infinite. I did find the types for node in the first stackblitz you referenced above and I had those put in yesterday.

Thanks so much @ChristianMurphy for your time and patience. 🙏 I've learned a lot more about how mdx works and I'm excited to about the possibilities it offers.

[ChristianMurphy]

Yes, I do use TypeScript on my local app, but I had its typechecking switched off for the admonition function after it was complaining that the type i added for tree was excessively large or possibly infinite.

🤔 The plugin itself should have tree as an mdast.Root node, everything inside the plugin should be able to infer the types from there (with minimal to no additional annotations). Just make sure remark-directive is in the type scope so it can add the directive node types into mdast.

Reference resources:

1. https://unifiedjs.com/learn/guide/syntax-trees-typescript
2. https://unifiedjs.com/learn/recipe/tree-traversal-typescript
3. https://unifiedjs.com/learn/recipe/narrow-node-typescript
4. https://unifiedjs.com/learn/recipe/build-a-syntax-tree/

[Firgrep]

Yep, I try to import the type root from (I've tried each of these in turn):

import { type Root } from '@types/mdast';
import type {Root} from 'mdast' // which is what I see used here: https://unifiedjs.com/learn/recipe/tree-traversal-typescript/
import type {Root} from 'remark-directive/lib' 
import type {Root} from 'mdast-util-definitions/lib'
import type {Node as MDASTNode } from 'mdast-util-definitions/lib'
type Root = import('mdast').Root

function adminitionPlugin() {
    return (tree: Root) => {
        visit(tree, (node: ContainerDirective | LeafDirective | TextDirective ) => {
          ....etc...

And they all bug out: Type instantiation is excessively deep and possibly infinite. 🤔