Extensible rendering proposal

[RadicalZephyr]

Hi there!

@reillysiemens and I have been working on cleaning up the customized Markdown processing in the Gutenberg static site generator, which uses pulldown-cmark for the base markdown processing.

For the most part, the extensions that "Gutenberg Flavored Markdown" would require can be accomplished just by manipulating the iterator of events before passing it to the renderer. However, for a few features, notably adding ids to h* tags and otherwise manipulating the internal portions of how specific tags are rendered doesn't seem to be possible with the current design.

We have started exploring implementing a more extensible structure in the html module that would allow reuse of the current commonmark html generation code, while also allowing the user to provide custom rendering behavior and even possibly their own event types. I've submitted a PR with our experimentation so far.

The basic gist of our approach is to introduce a new trait IntoHtml for rendering Events into HTML, move the current commonmark rendering to be done through the new trait, and then also expose enough of the current rendering implementation in a public API so that is available for reuse.

Hopefully this idea sounds interesting to you all, and if you have any feedback about what you think the end API should look like, that would be much appreciated. Also if I'm missing a way to customize how events are rendered please let me know!

Thanks!

[marcusklaas]

This seems to be the most highly requested feature, seeing as how this could solve these issues:

• footnote back-references: Footnote back-references #142
• tag overwrites: Add support for extending/overwriting handlers for tags #130
• custom link attributes: Configure link attributes as options #346

Unfortunately, it's not as easy as implementing IntoHtml for Event since some elements (tables and image alts are examples) need access to the event iterator and other state.

As I see it, there's three ways we could go about this:

1. Document how to write a custom renderer. It's not hard and it's not a lot of code. The default one included is around 400 LoC. Much of the functionality will likely be duplicated with the default renderer however.
2. Introduce a new, extensible HTML renderer. Maybe one where you'd supply a FnMut(Event) -> Option<String>, and the default behavior applying on Nones.
3. Extend the current HTML renderer with similar functionality, but providing access to internal write_str methods for lower overhead. Hopefully we can do this without affecting default performance.

[marcusklaas]

Quick update here: we have decided that the general approach of pulldown is to focus on parsing markdown, and only provide a simple renderer for basic, fast HTML generation. More advanced rendering features are encouraged to be built on top of markdown out-of-crate. In that spirit, we will not include more advanced rendering options in the near future and I'll close this issue for now. If you need more information out of pulldown for your rendering needs, please feel free to open another issue.