kramdown
kramdown copied to clipboard
gettalong
Suggestion for new syntax
::: summary part goes here
details part
goes here
:::
This would create <details> and <summary> elements. This appears to be extraordinarily common in Markdown, but everyone just uses HTML.
Introducing a new syntax will take a major version change for compatibility reasons and which is currently not planned anytime soon.
You could implement a custom syntax highlighter and (ab)use the fenced code block syntax for this which would not require any change to kramdown itself and be backwards compatible:
~~~ details
summary part goes here
details part
goes here
after blank line
~~~
The syntax highlighter would look for a code block with "language" details and do its custom thing, otherwise defer to the standard syntax highlighter in use.
That's extraordinarily clever, thank you.
Admittedly I was thinking of the 20-year future of Markdown, seeing that summary/details is very often written in Github issues/comments, and also that Jekyll uses Kramdown. But I don't know where to propose such a change to Markdown. And figuring that the spec usually follows implementation, I thought best to recommend it here.
But for my purposes, your solution is great. Thanks again.
The problem is that there is no common Markdown syntax. Each implementation differs in subtle and not so subtle ways. Luckily most syntax differences are small so running another implementation on some Markdown text will generally work okay-ish.
Well there's the CommonMark spec which I thought was pretty universal.
Also, the code-fence syntax hack wouldn't allow the body contents to be parsed as block-level Markdown.
Yes, CommonMark is a nice try but still not universal.
You could invoke a new parser instance in the custom syntax-highlighter that does the parsing.
Personally I kind of switched to using HTML for more complicated stuff.
For instance, nowadays for images I simply use plain HTML like:
<img src="some/URL.png" style="margin: 1em">
I found that I get a bit more control that way. For most other things I tend to avoid HTML in markdown, though. The reason why I switched to HTML for img-tags is mostly that, while I use kramdown to render the markdown for my gems on rubygems.org, I prefer the images to visually stand out a bit more, in particular screenshots. So a slight margin helps me visually. Not sure how others view that - people experience something differently.
Anyway enough of me digressing the issue here!
