Rename diagram.md to diagram.html, because it is HTML

[abitrolly]

Also use plain include directive

[joerick]

i guess this improves editor support?

[abitrolly]

And also clears the confusion that such diagrams are possible with pure markdown. )

[joerick]

Aah, i think i remember why i didn't do this. HTML is valid in markdown, but HTML blocks in markdown files can't have multiple newlines or the markdown parser starts to fiddle with it and insert <p> blocks or similar. So it has to be a single contiguous block without extra space in it. So we can't really think of it as regular HTML. Additionally, regardless of the file extension, the code is run through the markdown parser, as it's inserted verbatim into a markdown file, so the markdown quirks do apply in this file.

[abitrolly]

I am not sure included files are additionally processed, asked here - mondeja/mkdocs-include-markdown-plugin#187

It is not clear if the include is done before markdown is parsed and converted, or after.

[joerick]

The plugin works on the markdown before it's parsed by mkdocs.

[abitrolly]

@joerick mondeja/mkdocs-include-markdown-plugin#187 (comment) the answer is that no processing is done.

[joerick]

i'm pretty sure that he is saying that the plugin doesn't do any processing. But the plugin is working at the markdown level, mkdocs will still process it into HTML later.

[abitrolly]

Asked for additional clarification.

[mondeja]

The change makes sense to me, see this explanation: mondeja/mkdocs-include-markdown-plugin#187 (reply in thread)

[joerick]

Ah, I think I get it. I had the idea that multiple newlines broke markdown's parsing of HTML blocks, but I think this is where markdown parsers vary. In my editor, HTML blocks in markdown files have to be continuous, otherwise they don't preview/format correctly:

But I just tested it and it seems that mkdoc's markdown parser doesn't have the same limitation (agreeing with @mondeja's analysis).

(I suppose from a purity point of view, a pure HTML include directive would be cool, but it might also be a can of worms and including HTML-in-md seems to be working fine here.)