Ah I was under the impression it included markdown snippets :) (so it would parse the markdown file first for includes, parse those for includes using a set of already includes to avoid cycles etc. till no includes are found, merge included markdown in-place, then return that as the markdown to use). (which would require markdown parser adjustments)

Having @@include include literal fragments would make that of course not possible anymore. Hmm... Not sure what the best option is. @@include-html or @@includeliteral or @@includefragment all sound verbose.

It also might be done on-the-fly though: @@include("bla.md") is included into the markdown as-is, but so is @@include("bla.htm"). So before parsing/handling markdown. The markdown parser can deal with html, so that's not a problem (although I haven't tested that in full, e.g. a markdown pre block whether that's still converted or not I don't know). IF the markdown parser can deal with it without a problem, a recursive include is best, before parsing.

What are your thoughts on this?

I feel @@include on the fly is the best option as it is very simple to implement without touching the markdown parser. I really like the idea of embedding the source content before handing things over to markdown parser, that way the same include block can support both html and markdown.

Should be a very simple change. I will make it and submit a new pr. I can use the same approach for adding support for @@render tags also.

Sounds good! Your regexp version does a 1 level include I think? (the included markdown isn't parsed for include statements again). That's fine though, it can always be extended to be a recursive include :)