Support for WordPress WXR-style comment-based shortcodes and custom handling

[vadimkantorov]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything (or linked relevant results below)

Problem

These are WordPress export format (*.wxr) style shortcodes occur in exported HTML/XML. They are used for exporting some more precise info about standard blocks like wp:heading, but also for any custom blocks (e.g. some sorts of image galleries - for these blocks, some custom handling can be needed, e.g. to load the list of images from another exported JSON file and add it to the output).

<!-- wp:someshortcode {"some": "json, params"} -->
... some html or xml...
<!--/wp:someshortcode -->

or <!-- wp:someshortcode {"some": "json, params"} /-->

It's useful to be able to preserve the JSON-params of the standard/frequent blocks like wp:heading, and allow some custom processing/preservation of custom blocks.

This flow is important for content migration of WordPress's WXR -> more modern markdown remark/rehype-based static engines like Astro

Current solutions

Current solution would be to pre-process manually the these shortcodes in XML, and then use rehype to convert to Markdown format

Proposed solutions

Some built-in support for handlers of such format of WordPress-like shortcodes

[ChristianMurphy]

No, wordpress.com WXR will not be added directly to this.
This is for hast to mdast, aka html to markdown.
WXR is not html.

That said, unified is highly pluggable and makes it easy to create handlers and leverage existing utils.

You may want to leverage https://github.com/syntax-tree/xast-util-from-xml for parsing XML.

And then concert the xast to hast.

You'll also need to figure out what you want to short codes to become.
Directives? https://github.com/remarkjs/remark-directive
MDX? https://mdxjs.com/
Something else?

Happy to discuss more or answer questions in discussions.
https://github.com/orgs/rehypejs/discussions

Closing this issue, as the feature isn't a fit for this repo.

[github-actions]

Hi! This was closed. Team: If this was fixed, please add phase/solved. Otherwise, please add one of the no/* labels.

[vadimkantorov]

WXR itself is not html for sure, but WXR content field does contain html in its CDATA. And this field is often processed with rehype-remark to convert it to markdown, so hence my question of how to accomplish best handling of html-comment based shortcodes in rehype-remark.

Even outside of WordPress/WXR context, I think it's a valid question of how to handle best comment-based shortcodes within rehype-remark?

Maybe worth allowing the users to register some handlers? Or maybe it is already implemented?

Thanks for the pointers in every case!

[ChristianMurphy]

Even outside of WordPress/WXR context, I think it's a valid question of how to handle best comment-based shortcodes within rehype-remark?

Depends on your use case.
Directives are more portable and Markdown ish.
Mdx is more advanced, has some security trade offs https://mdxjs.com/docs/getting-started/#security but even more customizable than directives.

Maybe worth allowing the users to register some handlers? Or maybe it is already implemented?

There are handlers already 🙂

https://github.com/rehypejs/rehype-remark?tab=readme-ov-file#fields

https://github.com/syntax-tree/hast-util-to-mdast#handle