Markdown and line wrapping

Question

Most of the time Markdown files are treated just like source code: they're in a VCS, they take part in pull requests and/or reviews, and they're well formatted. And just like in source code, I often see inserted line breaks at a specific length—like a code formatter would do.

Many editors do that dynamically according to the current window size (a.k.a. word wrap). Furthermore, Markdown is mainly used to generate HTML pages, PDF documents, or other formats. Manually inserted line breaks often lead to messed up text rendering in these situations.

Is wrapping Markdown at a specific line length good or bad? The topic seems to be controversial, even the current CommonMark specification (v0.29) somewhat sits on the fence:

A regular line break (not in a code span or HTML tag) that is not preceded by two or more spaces or a backslash is parsed as a softbreak. (A softbreak may be rendered in HTML either as a line ending or as a space. The result will be the same in browsers. In the examples here, a line ending will be used.)

[…]

A conforming parser may render a soft line break in HTML either as a line break or as a space.

A renderer may also provide an option to render soft line breaks as hard line breaks.

However, John Gruber said back in 2004:

The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a <br /> tag.

When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a <br />, but a simplistic “every line break is a <br />” rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.

Answer 1

Most Markdown renderers ignore single linebreaks, so wrapping the text around some agreed-upon length won't affect the rendered outcome.

It would, however, potentially make the code much easier to maintain.

So it is not an anti-pattern and some projects even require it in their coding standards. Example from libstoragemgmt-doc:

" Set text width as 72.
autocmd Filetype markdown set tw=72

Answer 2

Good or bad is always depending on your viewpoint and context.

After having shifting preferences myself, I think the major divider is if you store them in a VCS, like git, or if you only write and read them for "personal use".

Using "one sentence per line" makes diffs "semantic" in the sense that it only affects lines/sentences that where changed. Having whole paragraphs reformatted and showing up in a git diff is... well, not nice. It hides the actual change with "presentation".

If that is not an issue, the sometimes longer and ragged lines makes reading, and writing, less pleasant, so in wikis, emails and such I tend to go for auto-reflow and limit lines as if I where typing a letter.

Markdown isn't actually presentation, it is source, so one way of looking at it is that we should not care so much about the readability of source if versioning is more important.

But one caveat with the "markdown is source" view is that not all renders render two lines with text as a paragraph but keep the linebreak as a "hard linebreak" causing the result to not be visually appealing either.