Pixel Envy

Written by Nick Heer.

Write Better Markdown

In a nut, if you can hand your Markdown file in its plain text format to someone who’s never read it before, and that person can read the file without difficulty, it’s good Markdown. I disagree with one of the things Brett Terpstra advises:

Markdown allows either inline ([text](url)) or reference format links. Either will work anywhere, and my personal preference is usually determined by the length of the document. Short documents get inline links. Longer ones get blocks of reference links. The readability is the determining factor.

I’ve switched to reference format links permanently; I think inline links are unreadable in almost every circumstance. Even using numerical reference links ([link text here][1]) is preferential to inline links, because [link text here](http://brettterpstra.com/2015/08/24/write-better-markdown/) really breaks this paragraph up, doesn’t it?