Semantic Line Breaks
All of our project documentation is written in Markdown.
It’s a simple, convenient format you can read in raw form without any
post-processing.
To keep Markdown documents readable and easy to edit later, I recommend
following the Semantic Line Breaks conventions.
It’s a small set of formatting rules that boil down to separating blocks
of text, lists, and other markup elements with blank lines.
I’m a bit surprised these conventions remain unknown to so many developers. Following them yields a pile of benefits:
- the raw document becomes easier to read;
- changes are simpler to inspect — in other words, it’s much easier to scan the output of
git diff [--word-diff]; - documents formatted with
Semantic Line Breaksare easier to edit.
To illustrate, here are two snippets.
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
- Item 1
- Item 2
- Item 3
Now let’s apply Semantic Line Breaks to the example above:
Lorem Ipsum is simply dummy text
of the printing and typesetting industry.
Lorem Ipsum has been the industry's standard dummy text
ever since the 1500s,
when an unknown printer took a galley of type
and scrambled it to make a type specimen book.
- Item 1
- Item 2
- Item 3
A few simple rules, and the resulting document is far more readable.
The Semantic Line Breaks conventions aren’t limited to Markdown. They’re
worth following when editing plain text files as well as files in other
markup languages, for example reST or AsciiDoc.