Update MD014/commands-show-output to allow blanks and output-less commands (fixes #241).

doc/Rules.md

@@ -298,8 +298,8 @@ when a single space is used after the list marker.
 
 Rationale (4 space indent): Same indent as code blocks, simpler for editors to
 implement. See
-<https://www.cirosantilli.com/markdown-style-guide/#indentation-of-content-inside-lists> for more
-information.
+<https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists>
+for more information.
 
 In addition, this is a compatibility issue with multi-markdown parsers, which
 require a 4 space indents. See
@@ -488,7 +488,7 @@ Tags: code
 Aliases: commands-show-output
 
 This rule is triggered when there are code blocks showing shell commands to be
-typed, and the shell commands are preceded by dollar signs ($):
+typed, and *all* of the shell commands are preceded by dollar signs ($):
 
 ```markdown
 $ ls
@@ -496,7 +496,7 @@ $ cat foo
 $ less bar
 ```
 
-The dollar signs are unnecessary in the above situation, and should not be
+The dollar signs are unnecessary in this situation, and should not be
 included:
 
 ```markdown
@@ -505,8 +505,7 @@ cat foo
 less bar
 ```
 
-However, an exception is made when there is a need to distinguish between
-typed commands and command output, as in the following example:
+Showing output for commands preceded by dollar signs does not trigger this rule:
 
 ```markdown
 $ ls
@@ -517,9 +516,18 @@ $ cat bar
 baz
 ```
 
-Rationale: it is easier to copy and paste and less noisy if the dollar signs
+Because some commands do not produce output, it is not a violation if *some*
+commands do not have output:
+
+```markdown
+$ mkdir test
+mkdir: created directory 'test'
+$ ls test
+```
+
+Rationale: it is easier to copy/paste and less noisy if the dollar signs
 are omitted when they are not needed. See
-<https://www.cirosantilli.com/markdown-style-guide/#dollar-signs-in-shell-code>
+<https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code>
 for more information.
 
 <a name="md018"></a>
@@ -986,7 +994,7 @@ of every item in the list consists of a single paragraph, or multiple
 paragraphs (including sub-lists and code blocks).
 
 For example, the style guide at
-<https://www.cirosantilli.com/markdown-style-guide/#spaces-after-list-marker>
+<https://cirosantilli.com/markdown-style-guide#spaces-after-list-marker>
 specifies that 1 space after the list marker should be used if every item in
 the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
 and unordered lists respectively) if there are multiple paragraphs of content

lib/md014.js

@@ -6,12 +6,36 @@ const { addErrorContext, filterTokens } = require("../helpers");
 
 const dollarCommandRe = /^(\s*)(\$\s+)/;
 
-function addErrorIfPreviousWasCommand(onError, previous) {
-  if (previous) {
-    const { lineNumber, lineTrim, column, length } = previous;
+module.exports = {
+  "names": [ "MD014", "commands-show-output" ],
+  "description": "Dollar signs used before commands without showing output",
+  "tags": [ "code" ],
+  "function": function MD014(params, onError) {
+    [ "code_block", "fence" ].forEach((type) => {
+      filterTokens(params, type, (token) => {
+        const margin = (token.type === "fence") ? 1 : 0;
+        const dollarInstances = [];
+        let allDollars = true;
+        for (let i = token.map[0] + margin; i < token.map[1] - margin; i++) {
+          const line = params.lines[i];
+          const lineTrim = line.trim();
+          if (lineTrim) {
+            const match = dollarCommandRe.exec(line);
+            if (match) {
+              const column = match[1].length + 1;
+              const length = match[2].length;
+              dollarInstances.push([ i, lineTrim, column, length ]);
+            } else {
+              allDollars = false;
+            }
+          }
+        }
+        if (allDollars) {
+          dollarInstances.forEach((instance) => {
+            const [ i, lineTrim, column, length ] = instance;
             addErrorContext(
               onError,
-      lineNumber,
+              i + 1,
               lineTrim,
               null,
               null,
@@ -21,33 +45,8 @@ function addErrorIfPreviousWasCommand(onError, previous) {
                 "deleteCount": length
               }
             );
+          });
         }
-}
-
-module.exports = {
-  "names": [ "MD014", "commands-show-output" ],
-  "description": "Dollar signs used before commands without showing output",
-  "tags": [ "code" ],
-  "function": function MD014(params, onError) {
-    [ "code_block", "fence" ].forEach((type) => {
-      filterTokens(params, type, (token) => {
-        let previous = null;
-        const margin = (token.type === "fence") ? 1 : 0;
-        for (let i = token.map[0] + margin; i < token.map[1] - margin; i++) {
-          const line = params.lines[i];
-          const lineTrim = line.trim();
-          const match = dollarCommandRe.exec(line);
-          if (!lineTrim || match) {
-            addErrorIfPreviousWasCommand(onError, previous);
-          }
-          previous = match ? {
-            "lineNumber": i + 1,
-            "lineTrim": lineTrim,
-            "column": match[1].length + 1,
-            "length": match[2].length
-          } : null;
-        }
-        addErrorIfPreviousWasCommand(onError, previous);
       });
     });
   }

test/code_block_dollar.md

@@ -1,3 +1,5 @@
+# Code Block Dollar
+
 The following code block shouldn't have $ before the commands:
 
     $ ls {MD014}
@@ -27,7 +29,7 @@ The following code block doesn't have any dollar signs, and shouldn't fire:
     cat bar
 
 The following (fenced) code block doesn't have any content at all, and
-shouldn't fire: {MD046:32}
+shouldn't fire: {MD046:34}
 
 ```bash
 ```
@@ -36,14 +38,39 @@ Mixed content:
 
     $ ls
     file.md other.md
-    $ git branch {MD014}
-    $ cat stuff {MD014}
+    $ git branch
+    $ cat stuff
 
     output
-    $ ls {MD014}
-    $ git branch {MD014}
+
+More mixed content:
+
+    $ ls
+    $ git branch
     $ cat stuff
     stuff here
     more stuff
     $ tail cat
     meow
+
+Command with blank lines in output:
+
+    $ dig example.com
+
+    ; ...
+    ;; ...
+
+    ;; ...
+
+Some commands with no output:
+
+    $ mkdir test
+    mkdir: created directory 'test'
+    $ cd test
+    $ ls test
+
+All commands with no output:
+
+    $ mkdir test {MD014}
+    $ cd test {MD014}
+    $ ls test {MD014}

test/code_block_dollar_fence.md

@@ -1,4 +1,4 @@
-# heading
+# Code Block Dollar Fence
 
 ```fence
 $ code {MD014}