I'd like to add an image gallery feature to my website. I'm sure there are hundreds Javascript plugins out there, or I could roll my own, but before I get there I have a bit of a problem with Markdown.
It's easy to embed arbitrary HTML into a markdown file - just add a <div>...</div>block on a new line and away you go. I've had to do this in a few places already. But I find this very invasive in the markdown, and for a complicated object like an image gallery, I'd end up writing more HTML than markdown - and then, what's the point in using markdown at all?
So I've been thinking of ways of creating a custom extension to Markdown, using the API provided by the Flexmark library used by Bascule. The API is challenging to work with and I'm struggling.
I'd like to be able to write a piece of markdown something like this:
!ยง[image gallery](2019/gallery/gallery.html)
The processor should read the contents of the file 2019/gallery/gallery.html and write them, as-is, into the generated page. There's no need for any additional processing, and it shouldn't impact Flexmark's internal model of the content.
I've got something working using code based on an existing Flexmark extension called media tags, and it almost works. Unfortunately, there's one fairly major problem.
My extension, like media tags, is an inline processor - these links can appear in the middle of a paragraph of text to create an HTML link element. When my extension appears on a line on its own, it is still considered to be part of a paragraph my Flexmark, and is wrapped in an HTML <p> block. This can completely invalidate the generated HTML.
As an example, given the following gallery.html file:
<div id="imageGallery">
<img src="pic1.jpg">
</div>
Then Flexmark takes my extension and produces the following HTML:
<p>
<div id="imageGallery">
<img src="pic1.jpg">
</div>
</p>
<div> tags are not allowed inside <p> tags!
I'm certain that this is a consequence of using an inline element like a link, rather than a block element such as the aside extension which creates <aside>...</aside> HTML blocks. I've tried to follow the example code from the aside extension, but it fries my mind too much, and it doesn't seem to fit well with the link extension approach.
I'm stumped for now, so I've asked a question on the github repository for Flexmark, and hopefully someone can point me in the right direction.
Update The creator of Flexmark has confirmed that I had taken the wrong approach in writing a link extension, and that I need a block extension. He has recommended I look at another sample extension, jekyll tags which also imports content from external files.