> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Literally the first paragraph from your link. I'm having trouble reconciling that first paragraph with the idea that it wasn't meant to be rendered as HTML.
I think you're talking past each other a little. Markdown was designed to let you "write HTML using an easy-to-read, easy-to-write plain text format", and to "be publishable as-is, as plain text". Those are both explicitly stated design goals.
The argument that GitHub is abandoning the "spirit of Markdown", I surmise, is that a README file written in Markdown should be equally readable whether you're reading it as rendered HTML or not. It may be a minor quibble in some respects, but I think it's a valid minor quibble. If I open your README file in my editor, I shouldn't have to run it through external software to make it comprehensible. I mean, maybe your project has an awesome logo, but would you just drop SVG code in the middle of the README file and tell me that if I was using the proper rendering engine it wouldn't be profoundly annoying? No, of course you wouldn't, because you're not a jerk. :)
Personally, I try to use only the "reference" style of links in README files so they look like "footnotes" when read as plain text, try not to include images unless they're both supplemental and really helpful when rendered on GitHub (e.g., screenshots for editor themes), etc. Mermaid seems like it would be awesome for generating diagrams for finished pages, but it doesn't seem at all like a good fit for READMEs.
It is still readable, though. It's not like there's a base 64 encoded blob in the middle. Mermaid is reasonably comprehensible (as reasonable as any other code block, at least) without any rendering.
“A text-to-HTML conversion tool” with the “overriding design goal” of “[making] it as readable as possible”.
You wrote:
> Markdown was meant to be rendered, not left as plaintext
Then the overriding design goal would not be to make it “as readable as possible” in its “raw” form (because what would be the point of that?). So this is clearly a falsehood.
Markdown was meant to be readable as-is. Meaning that you could read it as-is or render it. At your leisure.
Also literally your words:
> was meant to be a lightweight way
With the overriding goal of making it “as readable as possible”. Keyword “override”. Which means that it takes precedence over being “lightweight”.
Then you literally wrote:
> that it wasn't meant to be rendered as HTML.
Clearly a falsehood or a strawman as I only emphasized the “overriding design goal”. Markdown was supposed to be able to be rendered as HTML… and to be readable as-is.
The part that you were wrong about was this:
> Markdown was meant to be rendered, not left as plaintext
It was designed to be readable as plaintext as well… so this assertion of yours is false since it implies that plaintext readability was not a consideration. But it was in fact the primary design goal when making the syntax.
The "easy-to-read [...] plain text format" indicates to me that the idea was that markdown should be readable in plaintext form too. The ability to convert it to HTML is a different goal?
Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML. So what Github does with it (rendering README.md files) is perfectly compatible with that original intent. Just like everyone who used md->html renderers for their blogs or whatever other content.
If you just want plaintext, then you don't need markdown or any other markup. Just a plaintext file, like, I don't know, a README file. Don't throw .md (or .org in my case) on it, and it won't get rendered.
> Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML.
No, from day 1 it was meant to be readable as plain text and optionally rendered as HTML
Nobody is disputing that a key requirement of MD is to be machine parseable. What you’re missing is that another key requirement is for it to be human readable in plain text because it needs to be readable even when it hasn’t been rendered. Ie the rendering is an optional step but the format has to support one’s choice whether to render.
Rendering has HTML isn't really the issue, imo. The question is rather how readable the source remains, when you foget to fold lines, insert too many images without alt texts, intersperse regular HTML, etc.
Literally the first paragraph from your link. I'm having trouble reconciling that first paragraph with the idea that it wasn't meant to be rendered as HTML.