Add custom heading adapter

[lucperkins]

Fixes #267.

This PR adds a custom heading adapter akin to SyntaxHighlighterAdapter that can be used as the basis for plugins. Let me know if this is something you'd like to add and if you have any feedback on the API. To give an example, I have a project where I'd like to add some Tailwind/AlpineJS goodies directly into my headings, like this:

<h2 id="some-heading" x-data="{ showAnchor: false }" @mouseover="showAnchor = true" @mouseout="showAnchor = false">
  Some heading
  <a href="#some-heading" class="ml-2" x-show="showAnchor">#</a>
</h2>

One of many possible use cases, of course, but always nice to have a lever to pull 😄

Come to think of it, enabling custom headings would be a way to avoid issues like #250 and #261 without hard-coding API changes.

[kivikakk]

Outstanding. It occurs to me we probably want to let the heading adapter also take care of rendering the close tag? Otherwise they're restricted to only leaving open the exact <h1>…<h6> corresponding to the level given, since that's what we then close on the other side. This rules out uses where users may wish to transform the levels (e.g. render # as an <h4>), use a different tag entirely, nest the heading content in multiple tags, etc.

[kivikakk]

Let me know what you think of my suggestion; happy to merge whenever you're happy with what you've got, just mark as ready.

[lucperkins]

@kivikakk So, I chose not to let the adapter render the closing tag because I'm not quite sure how to pass in the AST content of the heading to the adapter. Take this heading as an example:

## Here is some `code` and some **bold** and some *italics* and even ~strikethrough~

In this case, you wouldn't want just the string "Here is some code and some bold and..." You'd want those nodes, too. If there's a good way to provide that, then we could indeed provide full control over the rendering. In my adapter implementation I pass over content as a string basically so that people can provide anchors but I leave the Markdown content untouched.

Update: I've come up with something that might work. As you can see, the adapter trait now has an enter method and an exit method. This preserves the content of the heading while providing total control over everything that wraps that content. I think it still might be better to just provide total control and pass in the level and the AST content and expect a string back. But I'm not quite sure how to do that.

[kivikakk]

As you can see, the adapter trait now has an enter method and an exit method. This preserves the content of the heading while providing total control over everything that wraps that content. I think it still might be better to just provide total control and pass in the level and the AST content and expect a string back. But I'm not quite sure how to do that.

I think this is perfect for now — giving the adapter the entire sub-AST to render could be problematic, because presumably it'd need some way to call back into the renderer (with appropriate state) if it just wanted to do business as usual. If a need for more complicated transforms comes up in the future, we can deal with it then.

[kivikakk]

I'm happy to merge this if you are. 👍

[lucperkins]

@kivikakk Happy to merge as well 😄 I did add some tests and bulked up the docs a teensy bit in the meantime if you want to take a look.

[kivikakk]

Awesome. Thank you so much!! 😊❤️