To Wrap or Not to Wrap in Markdown?

I keep antagonizing OSS contributors trying to wrap text in Markdown files, e.g. here and here.

Should one wrap text in .markdown files at 80 columns or should one not?

First, let me say that I don’t care. Except that I do. Wrapped text in markdown really feeds my OCD in the worst possible way, right behind missing periods at the end of sentences, and two spaces. Oddly, I don’t care about tabs vs. spaces.

Here’s a logical argument for not wrapping text in markdown.

Markdown doesn’t use line breaks: whether you include a line break in your markdown or not the rendered result is the same, unless you use 2 line breaks.

For example, consider the following text wrapped at 23 characters for illustration purposes.

A quick brown fox jumps
over the lazy dog.

We swap “a” and “the”, producing the following new text.

The quick brown fox
jumps over a lazy dog.

Because of a line wrap, this 2-word change is now a 2-line change. It hurts.

Without the wrap the diff would have been super clean.

>A quick brown fox jumps over the lazy dog.
<The quick brown fox jumps over a lazy dog.

Furthermore, GitHub does an even better job at the 1-line diff.

diff

Notice how the word “jumps” was highlighted, even though it wasn’t actually changed.

For an argument for wrapping text, see this comment.

Update: Enforce It

You can now enforce one source line per paragraph with markdownlint-rule-single-line-paragraphs, a custom markdownlint rule. See code.dblock.org#173 for a working example.

Here’s how to load the custom rule and enable it.

const rule = require("markdownlint-rule-single-line-paragraphs");

const options = {
  customRules: [rule],
  config: {
    "single-line-paragraphs": {
      enabled: true
    }
  }
};

The rule checks prose at the document root and inside lists and blockquotes. It preserves intentional Markdown hard breaks and <br> boundaries. It can also fix violations by joining continuation text onto the first line and deleting the old continuation lines.

I would have preferred this to be built as a new style: single in MD013 as discussed in markdownlint#298, but the repository doesn’t accept AI-generated code and I don’t remember how to write code anymore.

Daniel Doubrovkine

To Wrap or Not to Wrap in Markdown? markdown | open source

Update: Enforce It

To Wrap or Not to Wrap in Markdown?