How to parse/convert markdown to hast to render/display needed HTML?

[reypm]

I am trying to turn a markdown directive defined as:

:::notice{node}
This is a note notice
:::

into this HTML:

<div class="notice">
	<div class="notice-icon">
		<HiOutlineInformationCircle /> // this is coming from https://react-icons.github.io/react-icons
	<div>
	<div class="notice-content">
		This is a note notice
	</div>
</div>

But I am unsure how to turn such markdown into the properly hast and I will need some help/guidance. This is what I currently have:

const processNotice = (node: any) => {
    const allowedTypes = ['warning', 'important', 'note', 'tip', 'info'];
    const type = Object.keys(node.attributes)[0];

    if (allowedTypes.indexOf(type) === -1) {
        throw new Error('Invalid notice type: ' + type);
    }

    node.children.unshift({
        type: 'containerDirective',
        children: [
            {
                type: 'svg',
                data: {
                    hName: 'svg',
                    hProperties: {
                        class: node.name + '-icon',
                        variant: type
                    }
                }
            },
            {
                type: 'paragraph',
                children: [
                    {
                        type: 'text',
                        value: 'some'
                    }
                ]
            }
        ]
    });

    // node.children.push(img)
}

export default processNotice;

but as you can see in the runable example: https://codesandbox.io/s/muddy-hill-gvlrvs?file=/src/app.tsx is not working :| certainly I am missing something but unsure what it is. And this one is not as easy as others where I just built an object and push it back to the node childrens.

[wooorm]

The examples in the remark-directive readme might help: https://github.com/remarkjs/remark-directive#examples.

As mentioned before, it is recommended to use actual types if you prefer types, instead of any.

Also, your code is just messy: you are not using the plugin you are making in codesandbox? You are including other code for images, but not explaining what they should do? And why do images use an id, set to a URL? Wouldn’t it make more sense to call it url or src?

Here’s an example I made from your code to handle container directives with a name of image, as you have in the markdown:

/// <reference types="remark-directive" />
import type { Image, Paragraph, Root, RootContent } from "mdast";
import { visit } from "unist-util-visit";

/**
 * Plugin to support custom directives.
 */
const myRemarkShortcodePlugin: import("unified").Plugin<
  [],
  Root
> = function () {
  return (tree, file) => {
    visit(tree, (node, index, parent) => {
      if (
        node.type === "containerDirective" &&
        typeof index === "number" &&
        parent
      ) {
        if (node.name === "image") {
          const url = node.attributes.id;

          // Require an `url`, crash otherwise.
          if (typeof url !== "string") {
            file.fail("Expected `url` attribute on image directive", node);
          }

          // Create a markdown image node.
          const img: Image = {
            type: "image",
            url,
            alt: node.attributes.alt || undefined,
            title: null
          };

          // Images cannot be directly in things.
          // They are phrasing content.
          const paragraph: Paragraph = {
            type: "paragraph",
            children: [img]
          };

          // You also don’t want to *add* it to the directive,
          // you want to *replace* the directive.
          // @ts-expect-error: content model is fine.
          const siblings: RootContent[] = parent.children;
          // Replace directive with paragraph.
          siblings.splice(index, 1, paragraph);
        }
      }
    });
  };
};

export default myRemarkShortcodePlugin;

[reypm]

As mentioned before, it is recommended to use actual types if you prefer types, instead of any.

Yeah, I am trying my best there but having a hard time finding the right types to use 😞

Also, your code is just messy: you are not using the plugin you are making in codesandbox?

Fixed, I did not notice that

You are including other code for images, but not explaining what they should do?

The code for the image is just that it will display an image from the markdown

And why do images use an id, set to a URL? Wouldn’t it make more sense to call it url or src?

Sure, it makes sense but the shortcode (directive) developer used id and I cannot change that 🤦🏻

And as for your example, I am having a hard time getting it to work in Codesandbox and locally. I have created a repository feel free to make a PR if you want to.

[wooorm]

copy/paste the code I wrote in ShortcodePlugin.ts.
Import the plugin from App.tsx.
Use the plugin in remarkPlugins.
I wrote it in codesandbox, and it worked

[reypm]

@wooorm that is exactly what I did and is not working for me in Codesanbox

[wooorm]

You have different code in ShortcodePlugin.ts, here’s it pasted in: https://codesandbox.io/s/eager-varahamihira-2tg8mw?file=/src/customPlugins/ShortcodePlugin.ts

[wooorm]

codesandbox sometimes has issues with dependencies, I also removed and added unist-util-visit

[reypm]

hey @wooorm many thanks for this but I think you diverge from my OP and got distracted with the image code. Can I get some ideas for the notice one?

[wooorm]

1. Can you update a condesandbox with what you have?
2. What do you want with the node attribute? It’s in :::notice{node}
3. Are there other attributes you expect?
4. Why is HiOutlineInformationCircle used? Is it always that icon that is used?

[reypm]

Can you update a condesandbox with what you have?

Sure, here: https://codesandbox.io/s/muddy-hill-gvlrvs?file=/src/app.tsx

What do you want with the node attribute? It’s in :::notice{node}

The attribute will tell me what icon should I use. It maps as follows (meaning it can be any of those):

warning: <PiWarningLight />
important: <MdOutlineNotificationImportant />
note, info: <HiOutlineInformationCircle />
tip: <MdOutlineTipsAndUpdates />

Are there other attributes you expect?

No, just that one

Why is HiOutlineInformationCircle used?

This is because the attribute is note

Is it always that icon that is used?

No, it depends on the attribute.

Two extra things, the directive can be defined in two ways (don't ask me why 🤦🏻 is a pain) so I have to support both of them:

# Option 1
:::notice{note}
This is a note notice
:::

# Option 2
:::notice{title=node}
This is a notice node
:::

That's why my solution has this piece of code (I am open to suggestions and/or improvements 😎 ):

  const allowedTypes = ["warning", "important", "note", "tip", "info"];
  const firstElementKey = Object.keys(node.attributes)[0];

  let currentType;

  // Require a `type` attribute, crash otherwise.
  if (Object.hasOwn(node.attributes, "title")) {
    currentType = node.attributes.title;
  } else if (allowedTypes.indexOf(firstElementKey)) {
    currentType = firstElementKey;
  } else {
    file.fail("Expected `type` attribute on notice directive", node);
  }

The HTML I want to output was missing something, here is the correct one:

<div class="notice">
	<div class="notice-icon">
		<HiOutlineInformationCircle /> // this is coming from https://react-icons.github.io/react-icons
		Note //This is the attribute, it goes here
	<div>
	<div class="notice-content">
		This is a note notice
	</div>
</div>

I am not wrapping the text or the icon inside other elements but feel free to do it as needed, I need to keep the containers and the classes so the UI/UX team can play with them and get what they want

[reypm]

@wooorm Currently my approach is not working as you can see in the Codesandbox, I wonder if I need to use remark-html for this to get it working 🤔

[ChristianMurphy]

@reypm with a minimal reproducible example, aim to remove as many unrelated pieces as possible.
There are a lot of random plugins which are unrelated to your question on directives which make it harder to interpret and debug.

Back on your question of how to handle a notice.
Focus on how you want the mdast directive to translate to hast, using the data attributes in mdast https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes.

import type { VFile } from "vfile";
import type { Blockquote, ListItem } from "mdast";
import type { Element } from "hast";
import type { ContainerDirective } from "mdast-util-directive";
import type { FootnoteDefinition } from "mdast-util-gfm-footnote";
import { toHast } from "mdast-util-to-hast";

/**
 * This will be called by `unist-util-visit` for each `containerDirective` in the document.
 */
function mdastContainerDirectiveVisitor(
  node: ContainerDirective,
  index: number,
  parent: Blockquote | FootnoteDefinition | ListItem | ContainerDirective,
  file: VFile
) {
  const allowedTypes = ["warning", "important", "notice", "tip", "info"];

  /**
   * Do any validation here and attach details any issue(s) on the vFile object
   */
  if (!allowedTypes.includes(node.name)) {
    file.fail("notice directive: invalid type", node);
  }

  // make sure data exists
  node.data = node.data ?? {};
  // tell remark-rehype what kind of HTML element to use for this directive
  node.data.hName = "section";
  // add attributes to the HTML element to allow you to differentiate the type
  node.data.hProperties = {
    // Using a CSS class name for example
    className: node.name
  };
  const hastChildren: Element[] = [
    // add the icon and label at the top
    {
      type: "element",
      tagName: "div",
      properties: { className: "notice-icon" },
      children: [{ type: "text", value: node.name }]
    },
    // add the content
    {
      type: "element",
      tagName: "div",
      properties: { className: "notice-content" },
      // translate directive inner content from mdast to hast
      // @ts-expect-error not all content types can be translated as inner content of element
      children: node.children.map(toHast)
    }
  ];
  node.data.hChildren = hastChildren;
}

export default mdastContainerDirectiveVisitor;

Runnable example: https://codesandbox.io/s/remark-directive-5lll3p?file=/src/customPlugins/Shortcodes/Notice.tsx

---

@reypm for future questions, focus on one question at a time.
Aim to reduce the question to a minimal reproducible example (https://stackoverflow.com/help/minimal-reproducible-example)
Saying a snippet of random code is "not working" doesn't give people helping you much useful context, which is frustrating for us trying to help you, aim to include the information outlined in the support guidelines https://github.com/remarkjs/.github/blob/main/support.md

[reypm]

for future questions, focus on one question at a time. Aim to reduce the question to a minimal reproducible example

Hi @ChristianMurphy lesson learn from now on I will try to be as much strict as possible when asking a question and thanks for the well-explained example, is more clear to me.

[reypm]

hey there @ChristianMurphy, some doubts:

1. how do I support Leafs directive as well? 🤔 The following line only support containerDirective:

visit(tree, "containerDirective", (node, index, parent) => { ...

2. can I add custom properties like for example variant to the properties object while defining an Element?

{
  type: 'element',
  tagName: 'span',
  properties: {
    className: currentType,
    variant: 'some value'
  },
  children: []
},

The only information I could find about the allowed properties was:

export interface Properties {
    [PropertyName: string]: boolean | number | string | null | undefined | Array<string | number>;
}

any docs I should read? 🤔

I have updated the runnable example: https://codesandbox.io/s/remark-directive-forked-hv63jx

[ChristianMurphy]

how do I support Leafs directive as well?

There are three types of directives, containerDirective, leafDirective, and textDirective`.
https://github.com/syntax-tree/mdast-util-directive#directives

visitor in your example uses Test as its second parameter.
https://github.com/syntax-tree/unist-util-is#test
In this case an array test would allow you to capture as many or as few directive types as wanted.

visit(tree, ["containerDirective", "leafDirective", "textDirective"], (node, index, parent) => { ...

can I add custom properties like for example variant to the properties object while defining an Element?

Sure, you can any pretty much anything to properties.
I'd recommend sticking with the HTML standard, and using a data- prefix for anything custom https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes
But that isn't a requirement imposed by hast/rehype.

[reypm]

@ChristianMurphy / @wooorm one more and last thing: while running npm run build the linting is failing with the following error:

Type error: Property 'name' does not exist on type 'ContainerDirective | LeafDirective | Blockquote | FootnoteDefinition | ListItem | HTML | ... 23 more ... | FootnoteReference'.
  Property 'name' does not exist on type 'Blockquote'.

  23 |     visit(tree, ['containerDirective', 'leafDirective', 'textDirective'], (node, index, parent) => {
  24 |       if (typeof index === "number" &&parent) {
> 25 |         switch (node.name) {

node.name is being used as follows in my custom plugin:

const myRemarkShortcodePlugin: import("unified").Plugin<
  [],
  Root
> = function () {
  return (tree: Root, file: VFile) => {
    visit(tree, "containerDirective", (node, index, parent) => {
      switch (node.name) {
        // case "image": {
        //   processImage(node, index, parent, file);
        //   break;
        // }
        case "notice": {
          processNotice(node, index, parent, file);
          break;
        }
      }
    });
  };
};

is there any other property that I can use for the switch statement?