remark@next (13)

[wooorm]

Hi!

remark is switching to a new parser (and compiler) internally (micromark, remarkjs/remark#536), which will break this plugin. I will create a generic directives plugin though, time permitting, in this month, which would be a good inspiration for admonitions. Keep an eye out for that plugin, which will be small wrapper code around micromark and mdast extensions, and feel free to ask me questions!

[elviswolcott]

Wow, seems like some great improvements! I'm pretty busy with school right now but will try to find some time to update this plugin.

[wooorm]

I have created a micromark extension for my interpretation of the generic directive syntax: https://github.com/micromark/micromark-extension-directive And a corresponding utility for mdast: https://github.com/syntax-tree/mdast-util-directive And wrapped ’em all up in: https://github.com/remarkjs/remark-directive

I hope those serve as inspiration: note that you don’t have to split them up in several repos, but that’s how I like to work.

Finally, something like remark-admonitions can be done with remark-directive too, where remark-directive handles the syntax and tree, and remark-admonitions changes the tree to create HTML?

[mmsinclair]

@elviswolcott @wooorm if you would be open to it, I'd be happy to have a go at this and submit as a PR?

I use unist/remark a lot in a product we have that is written mostly in Typescript, so I hope I'm in a good position to contribute here. At the moment, I have a pressing need to have admonitions working with micromark and MDX@next, because we create output that gets rendered in a Docusaurus static site and the content has lots of admonitions.

@elviswolcott, I don't want to inadvertently steal your thunder 😀 so if you'd rather do this yourself, then please feel free to say so. I'm going to do something about this anyway for us internally in some shape or form to get this moving, and my preference would be to work with you guys to update this plugin so everyone can use it with micromark, because I imagine there are others who need it?

I have had a good look through https://github.com/micromark/micromark-extension-directive and https://github.com/syntax-tree/mdast-util-directive and I'm going to have a go at doing something on my own first and then it would be very useful if @wooorm could give me some pointers and tips?

I am also expecting some Typescript turbulence e.g. where there aren't typings for things etc. I'm thinking I might start in plain JS first (with https://github.com/micromark/micromark-extension-directive as a base) to get it working and then migrate it to Typescript.

[wooorm]

@mmsinclair See https://github.com/micromark/micromark/discussions for some existing information, and feel free to ask more Qs there. In particular see https://github.com/micromark/micromark/discussions/54#discussioncomment-693101.

I am personally quite productive in JS compared to TS, so I’d suggest sticking with that first, if it works for you too. I’m currently 50% through all of unified adding types, and micromark is up next soonish (but it’s quite a complex project to type)

[jlvandenhout]

Any updates on this? I have a need to parse Docusaurus docs dynamically using a unified pipeline, so I was wondering if any of you got a chance to have a look at this. I would love to try and help as well!

[mmsinclair]

@jlvandenhout apologies for the slow reply, I unfortunately had to pause work on this because my startup ran out of funding 😞 and I've had to wind it up, so that has taken up a fair chunk of my time recently.

However, I have made some progress on this and spent a few hours dusting off where I got to. I've mostly done the parsing of the admonition into AST nodes (I'm hoping this will be useful for you) and got a way through the transform to HTML. There is a fair amount of tidy up to do (e.g. making sure the test coverage is good and some docs of how I implemented it) and I need some review time from @wooorm, before it could be released.

Unfortunately I can't really commit to any timescales for having something useful for you. However, it would be good for you to try out the parser I've written at some point, so I can get some feedback on it.

Out of interest, do you need to inspect/manipulate what is inside the title and content areas of the admonitions? Or is the dynamic bit other parts of the file and you need the admonitions to be left intact after processing?

[wooorm]

@mmsinclair Let me know what and when I can review. Also: I released a new version of micromark et al yesterday, which includes a lot of docs on extensions

[jlvandenhout]

@mmsinclair No worries, I'm not in a hurry at all! For a project we are building we would like an in-page editor, which I'm implementing using TipTap together with a Unified pipeline that closely resembles the Docusaurus rendering pipeline to get from dynamically loaded Markdown to HTML. I'll only be using the HTML output of this plugin. I don't necessarily need to manipulate anything, so me saying I needed the plugin to "parse" the docs might have been a bit poor wording from my side :)

[mmsinclair]

@wooorm I've started a discussion here (https://github.com/micromark/micromark/discussions/70)