Using Markdown effectively

Updated on .

Markdown is a way to style plain text documents without needing to edit them with a word processor like Microsoft Word. Markdown keeps me from getting distracted by typefaces, font sizes, and margins, while still giving me tools to embed links, code, and emphasis. It lets me use whichever text editor is most convenient (usually iA Writer) and then prepare it for publication using other, more specialized tools. 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 that supports reflowing text and remembering to reflow it when editing an existing paragraph and gives a strong hint to tools about where sentence breaks are vs. abbreviations. This technique is similar to how roff is typically formatted and is called semantic line breaks, 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 inline links, depending on the context. For lists and ephemeral-feeling links, I use inline links with the URL next to the link, like [this](url). When writing a typical document, I’ll make references out of the URLs and keep all of the definitions at the bottom of the document, sorted so it’s easier to find a reference by its ID. I prefer to use the link text as the reference ID, 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:

- [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.

[semantic linefeeds]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
[latex-guide]: https://github.com/dspinellis/latex-advice "Diomidis Spinellis's guide to writing LaTeX effectively for collaboration and research."

All of the content on this website is stored as Markdown and converted to HTML; the details are explained in the Colophon. On my computer, I name the files with the .md file extension, instead of .markdown or .txt. Changing the extension of any note on this website from .html to .txt opens its Markdown source.

References