Make Default AST -> HTML Transformation pluggable, was: Question: Is there a way to extend the transformation from AST to HTML?

[fedme]

I would like to provide a custom HTML renderer for certain markdown element types. For example, I would like to render links in some custom way.

I've searched through the docs and past issues but I could not find a documented way of achieving this.

I understand that I can use Earmark.as_ast to get the AST from the raw markdown and then Earmark.Transform.transform to transform the AST to HTML.

Is there a way to plug a function in between that transforms a specific markdown element type to some custom HTML and then use the default transform for all other markdown element types?

Ideally I imagine this as an option passed to Earmark.Transform.transform that says "for elements of type link use this custom render function".

Thanks!

[RobertDober]

This has come up quite some times now and I understand that this is a good idea, so that was the good news, the bad news is that I have virtually no time do work on Earmark right now, and it does not look like I will have soon.

Let me rephrase this and put it into the 1.5.1 Milestone, but even for 1.5 which contains bugfixes and necessary AST changes I do not have an ETA. :(

[RobertDober]

Alternative Idea, create an EarmarkASTTransformer project based on the v1.5 AST API and just leave (and maybe even deprecate) the current HTMLTransformer intact. @josevalim @wojtekmach can I count 100% on ex_doc not using as_html anymore? And @pragdave we have discussed such things before but if ex_doc uses as_ast maybe this would be ok with you.

[wojtekmach]

can I count 100% on ex_doc not using as_html anymore?

Yes. We're definitely only interested in ast output going forward.

[fedme]

Thanks for answering so quickly! I would love to help but I am new to elixir and this task seems a bit complicated with my current skills...

[RobertDober]

Appreciated if I had time to work on Earmark I would love to guide you but right now the code base is not in a friendly state, some backports etc...

si direbbe ch'é un gran' casino, ma noi, questo tipo di lingua non l'applichiamo, giusto? ;)

[josevalim]

I honestly think the best course of action here is to document the AST, so anyone who wants to render it in their own way can do it based on its public format and Earmark doesn't have to worry about it. :)

[fedme]

Yes, that's what I will do since I only need to render a few markdown elements (titles, text, links and images).

I will post here my custom AST renderer once it's ready, in case it's useful to anybody else.

In the future I think it would be nice to fallback to the default renderer for those elements that you don't need to customize.

Thanks again for the useful insights and I hope to help once I'm more skilled in Elixir :)

Hopefully the code will be less of a "gran casino" by then 😅.

[RobertDober]

Your optimism belongs to you :wink: , but would you be interested in writing a pluggable AST->HTML transformer and publishing it to hex? Actually the AST spec is stable, just not implemented yet, I might sacrifice a weekend or two to backport it to 1.4.5 would love to get that done for ex_doc too. Then I can concentrate on the bugs while you can do all the fun stuff in the transformer :blush:

Puoi enviarmi una mail privata se vuoi. mailto: robert.dober <AT> gmail

[RobertDober]

@josevalim I guess I really have to find the time to do the little changes for ex_doc to get the pressure off Earmark.

[oliverswitzer]

@fedme were you able to create that custom AST parser? Am running into a similar issue that would require modifying the way the AST is transformed into html.

[fedme]

@oliverswitzer I didn't have much time to implement an elegant solution, so what I did was to copy the Transform module from this repo and modify it with the additional transformations I needed. Then I simply used the transform function from my module rather than from this repo.

You can see my ugly hack here.

I hope this helps you somehow...