Using Markdown effectively

Updated on .

I love writing in Markdown because it keeps me from focusing on how my text is presented, while still giving me tools to embed links, code, and emphasis. It lets me use whichever text editor is most convenient and then prepare it for publication using other, more specialized tools (that I can even write myself!). Unlike a WYSIWYG editor like Word or Pages, I’m not bothered by the font or paragraph spacing, and can defer those decisions to later. Over the years I’ve written in Markdown, I’ve developed some habits and best practices for keeping it maintainable and clear.

Line breaks

Instead of reflowing text to fit in a certain column limit, or allowing text to be reflowed entirely by the editor with “soft wrapping,” I add a line break after each sentence. This allows version control systems to track changes on a per-sentence basis, as opposed to per-80 columns or per-paragraph. This also saves me from needing an editor editor that supports reflowing text and remembering to reflow it when editing an existing paragraph. It also gives a strong hint to tools about where sentence breaks are vs. abbreviations. This technique is similar to how roff is typically edited and is called semantic linefeeds (or, archaically, ventilated prose). I don’t go as far as breaking lines on fragments or lists, but I may try that in the future. Sentences seem like a good compromise between vertical and horizonal space usage. This echoes some of Diomidis Spinellis’s Advice for writing LaTeX documents, specifically on how to Write readable and maintainable LaTeX source code.

Using semantic linefeeds in the first paragraph of a list item is challenging because it’s not clear how to indent subsequent sentences. For a while, I was indenting them by two spaces to be aligned with the first sentence. I stopped doing that when it became too cumbersome to use with my editor, and now leave them unindented. It looks a bit strange, with subsequent sentences not aligned with the first, and I could potentially break just after the hyphen, like this:

-
The first sentence.
The second sentence.

But that syntax doesn’t parse as a list item unless there’s a trailing space on the hyphen. It also doesn’t really make sense for a single-sentence list item.

I use a combination of reference and embedded links, depending on the context. For lists and ephemeral-feeling links, I embed the URL next to the link, like [this](url). When writing longer paragraphs, or if I want to reference the URL again, I’ll make references out of the URLs. I prefer to use the link text as the reference, if possible, so there’s less metadata in the prose, but if the link isn’t a proper noun, I’ll shorten the reference to a hyphenated phrase.

Wherever I can, I try to include a description of the link, which is added to the title of the anchor and can be read by screen readers.

Example

This is a normal paragraph.
It happens to use [semantic linefeeds][] that I was first exposed to in a [guide to using LaTeX][latex-guide].
Here are some sites I visit frequently:

[latex-guide]: https://github.com/dspinellis/latex-advice "Diomidis Spinellis's guide to writing LaTeX effectively for collaboration and research."

- [Hacker News](https://news.ycombinator.com)
- [Lobste.rs](https://lobste.rs)

And another list with paragraphs:

- This list item has multiple sentences.
These sentences are separated by linebreaks.

Resources

There’s always RFC 7764.