Help converting an HTML span to a Markdown directive

[dmca-glasgow]

Hi there,

In the past I have used unified to convert Markdown to HTML, and when I made a custom transformation, I used the hast properties (hName, hProperties, hChildren) in the mdast AST.

However, I'm now tasked with converting HTML to Markdown and there doesn't seem to be a similar way to do this?

My specifc problem is converting a span with class to a leaf directive:

<p>My content and <span class="sidenote">my <b>sidenote</b></span>.</p>

should become:

My content and ::sidenote[my **sidenote**].

Where in this processor should I put my custom transformation, and what would it look like?

import { unified } from 'unified';
import rehypeParse from 'rehype-parse';
import rehypeRemark from 'rehype-remark';
import remarkStringify from 'remark-stringify';

const file = await unified()
  .use(rehypeParse)
  .use(rehypeRemark)
  .use(remarkStringify)
  .process(`<p>My content and <span class="sidenote">my <b>sidenote</b></span>.</p>`)

console.log(String(file))

// current output is:
// My content and my **sidenote**.

Thanks for any help.

[wooorm]

Hey!

The h* fields are indeed also a good way to do this, the other way around, mdast -> hast.
Such a thing does not exist hast -> mdast.

But, what is also possible, is to hook into the place where the conversion between the ASTs happens. remark-rehype and rehype-remark.

They both support handlers:

handlers (Record<string, Handle>, optional) — object mapping tag names to functions handling the corresponding elements; merged into the defaults; see Handle in hast-util-to-mdast

There you would use span as a key, and write a handler that generates a text directive: https://github.com/syntax-tree/mdast-util-directive#textdirective.

[dmca-glasgow]

Thanks for your help @wooorm,

I ended up with something like this:

import { unified } from 'unified';
import rehypeParse from 'rehype-parse';
import rehypeRemark from 'rehype-remark';
import remarkStringify from 'remark-stringify';
import remarkDirective from 'remark-directive';
import { toMdast, State } from 'hast-util-to-mdast';
import { TextDirective } from 'mdast-util-directive';
import { Parent, PhrasingContent } from 'mdast';
import { Element } from 'hast';

const file = await unified()
  .use(rehypeParse)
  .use(rehypeRemark, {
    handlers: {
      span: customSpanHandler,
    },
  })
  .use(remarkDirective)
  .use(remarkStringify)
  .process(`<p>My content and <span class="sidenote">my <b>sidenote</b></span>.</p>`);

function customSpanHandler(state: State, node: Element) {
  if (node.properties.className?.toString() === 'sidenote') {

    const root = toMdast({
      type: 'root',
      children: node.children,
    }) as Parent;

    const result: TextDirective = {
      type: 'textDirective',
      name: 'sidenote',
      children: root.children as PhrasingContent[],
    };

    state.patch(node, result);
    return result;
  }

  return state.all(node);
}

console.log(String(file));
// My content and :sidenote[my **sidenote**].

What stumped me for quite a while was that leafDirective has to have it's own line, and textDirective is more suitable for the 'inline' scenario (with just the one :).

If anything can be improved please let me know as I have to write a lot of these!

[wooorm]

Looks good, main thing is I wouldn’t call toMdast in there. You can use state to do that. See:
https://github.com/syntax-tree/hast-util-to-mdast/blob/52b3d5a715da233d15b711c5475d1cf40480a7cc/lib/handlers/a.js for example.

And, I’d go with a different condition. So, something along the lines of this pseudo code:

function customSpanHandler(state: State, node: Element) {
  if (
    Array.isArray(node.properties.className) &&
    node.properties.className.includes('sidenote')
  ) {
    const result: TextDirective = {
      type: 'textDirective',
      name: 'sidenote',
      children: state.all(node) as Array<PhrasingContent>
    }

    state.patch(node, result)
    return result
  }

  return state.all(node)
}

[dmca-glasgow]

Great, thanks for the useful suggestions!