Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: