14 ms·
The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe
by daptaq 5y ago
The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository.
It should really be called RENDERME.
- glennvtx 5y agoREADME.HTML
- PinguTS 5y agoMarkdown has always been about "renderme". From the beginning. If you want a simple README, then do a README and not a README.md.
- Someone 5y agoThe first paragraph of https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/: “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).” ⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML. That’s similar to how SwiftUI’s struct ContentView: View { var body: some View { Text("Hello World") } } is deemed an improvement over, for example, Java Swing’s JFrame frame = … JLabel label = new JLabel("Hello World"); frame.getContentPane().add(label); but in both cases, it’s the result that counts.
- deleted 5y ago[deleted]
- zamadatix 5y agoFrom your same link it does not say un-rendered readability was a secondary goal, it says the exact opposite: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. This also fits with the ordering from the second paragraph: > Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. Markdown has always included rendering capability as a goal but I think GP is right, Markdown was never intended to be an always render first format just because it included the capability to render.
- avgcorrection 5y ago> It should really be called RENDERME. Hah—yes!
- spoils19 5y agoRENDERME, nice one!
- didericis 5y agoWhich specific github flavored features violate the original spirit of markdown? I only use the basic syntax, but I don’t think I’ve run across a readme edit that hasn’t adhered to that original spirit.
- daptaq 5y agoMy go-to example is uBlock: https://raw.githubusercontent.com/gorhill/uBlock/master/README.md https://raw.githubusercontent.com/gorhill/uBlock/master/READ..., despite being a great add-on, has 1/3-1/2 of unlegible Markdown, that looks nice when rendered.
- anderspitman 5y agoI don't think GP was suggesting that there's anything specific wrong with GFM, but more that the way github encourages READMEs to be used (by auto-rendering all READMEs to HTML) creates an abstraction that shadows the readable-as-text goals of markdown.
- Jtsummers 5y ago> readable-as-text goals of markdown. Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight markup language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.
- laumars 5y ago> Markdown was meant to be rendered, not left as plaintext Now it’s not. Markdown was intend to be legible in plain text but visually emulate rendered text. The rendering stuff came later but even then it still had an emphasis on plain text readability. There is a reason it was chosen for README, INSTALL etc documents in project repositories that are (or, at least until relatively recently in computing history, were) traditionally read in the command line.
- julienb_sea 5y agoTo be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.
- darknavi 5y agoAssuming that those tools also implement the same set of MD functionality (like Mermaid)
- armchairhacker 5y agoWe need to go back to something like Word documents. We’ve come full circle
- crabmusket 5y agoREADME.docx
- seanw444 5y agoAt least do LibreOffice format.
- dotancohen 5y agoIf I ever see that in the wild, I'm going to escalate the arms race with a README.xml file.
- 5y ago
- tomrod 5y agoI'm getting vibes of "MOISTURIZE ME" from Doctor Who.