Merge pull request #138 from mobify/markdown-lint-rule-tweaks

jeremywiebe · web-flow · commit 2a2f2f0fcb2b · 2016-11-30T08:46:52.000-08:00
Markdown lint rule tweaks
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,7 @@
+# To be released
+    - Re-organized and cleaned up markdown linting files
+    - Switched to using `no-duplicate-headings-in-section` (instead of `no-duplicate-headings`)
+
 2.7.0
     - Remove `variable-for-property` rule from sass-lint
     - Adds markdown linting via `lint-md` script
diff --git a/README.md b/README.md
@@ -3,6 +3,7 @@
 A repo to document code standards for different languages and provide tools for linting Mobify projects.
 
 [![NPM version](https://badge.fury.io/js/mobify-code-style.svg)](http://badge.fury.io/js/mobify-code-style)
+[![CircleCI](https://circleci.com/gh/mobify/mobify-code-style/tree/develop.svg?style=svg)](https://circleci.com/gh/mobify/mobify-code-style/tree/develop)
 
 ## JavaScript (ES5) with Grunt
 
@@ -25,7 +26,6 @@ extends:
   - './node_modules/mobify-code-style/es5/mobify-es5.yml'
 ```
 
-
 Sample eslint Grunt config:
 
 ```javascript
@@ -103,4 +103,4 @@ instructions on using `pep8`, `pylint` and `pyflakes` to check Python code.
 
 ## Documentation
 
-See the [`docs`](docs) directory for setup and configuration of Markdown linting.
+See the [`docs`](docs) directory for setup and configuration of Markdown linting.
diff --git a/bin/lint-md b/bin/lint-md
diff --git a/bin/lint-md b/bin/lint-md
@@ -0,0 +1 @@
+../docs/bin/lint-md
diff --git a/docs/README.md b/docs/README.md
@@ -49,5 +49,5 @@ What kind of document best meets your goal?
 
 **After writing**
 
-* [ ] 👍 Reviewer
+* [ ] 👍 Review
 * [ ] 🍻 Celeberate
diff --git a/docs/bin/lint-md b/docs/bin/lint-md
@@ -0,0 +1,19 @@
+#!/bin/bash -eu
+
+# Lints Markdown files using Mobify's `.remarkrc` configuration.
+BIN="${BASH_SOURCE[0]}"
+BIN_DIR="$(cd "$(dirname "$BIN")" && pwd)"
+
+# We jump through some hoops here because we symlink the node module's
+# bin into the docs/bin/ directory and we want to support invoking
+# via the symlink and directly via `/docs/bin/lint-md`
+if [ -h "$BIN" ]; then
+    # Dereference the symlink
+    BIN="$BIN_DIR/$(readlink "$BIN")"
+fi
+BIN_DIR="$(cd "$(dirname "$BIN")" && pwd)"
+
+REMARK_RC="$BIN_DIR/../remarkrc"
+REMARK_CLI="$(npm bin)/remark"
+
+$REMARK_CLI --rc-path $REMARK_RC "$@"
diff --git a/docs/remarkrc b/docs/remarkrc
@@ -16,21 +16,14 @@
         "maximum-heading-length": 60,
         "maximum-line-length": 80,
         "no-consecutive-blank-lines": true,
-        "no-duplicate-headings": true,
+        "no-duplicate-headings-in-section": true,
         "no-file-name-articles": true,
-        "no-file-name-articles": true,
-        "no-file-name-consecutive-dashes": true,
         "no-file-name-consecutive-dashes": true,
         "no-file-name-irregular-characters": true,
-        "no-file-name-irregular-characters": true,
-        "no-file-name-mixed-case": true,
         "no-file-name-mixed-case": true,
         "no-file-name-outer-dashes": true,
-        "no-file-name-outer-dashes": true,
-        "no-heading-content-indent": true,
         "no-heading-content-indent": true,
         "no-heading-indent": true,
-        "no-heading-indent": true,
         "no-multiple-toplevel-headings": 0,
         "no-table-indentation": true,
         "no-tabs": true,
@@ -40,4 +33,4 @@
         "unordered-list-marker-style": "-"
     }
   }
-}
+}
diff --git a/docs/test/a-bad-filename.expected.md b/docs/test/a-bad-filename.expected.md
@@ -0,0 +1,5 @@
+
+a-bad-filename.md
+  1:1  warning  Do not start file names with `a`  no-file-name-articles  remark-lint
+
+⚠ 1 warning
diff --git a/docs/test/a-bad-filename.md b/docs/test/a-bad-filename.md
diff --git a/docs/test/bad.expected.md b/docs/test/bad.expected.md
@@ -14,7 +14,7 @@ Used to test violations of style.
 
 BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
 
-BAD: List immedidately following text.
+BAD: List immediately following text.
 
 -   list
 
@@ -44,21 +44,20 @@ BAD: Indented code-block.
     # Indented code block
 
 BAD: Missing newline at end of file.
-docs/test/bad.md
-         1:1  warning  Missing newline character at end of file                final-newline                  remark-lint
-    7:1-7:43  warning  Heading levels should increment by one level at a time  heading-increment              remark-lint
-    9:1-9:33  warning  Don’t use multiple top level headings (9:1)             no-multiple-toplevel-headings  remark-lint
-  13:1-13:27  warning  Do not use headings with similar content (11:1)         no-duplicate-headings          remark-lint
-      15:104  warning  Line must be at most 80 characters                      maximum-line-length            remark-lint
-        18:5  warning  Incorrect list-item indent: remove 2 spaces             list-item-indent               remark-lint
-        26:4  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
-   30:1-30:8  warning  Marker style should be `-`                              unordered-list-marker-style    remark-lint
-        30:4  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
-        34:5  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
-   35:1-35:9  warning  Marker should be `2`, was `1`                           ordered-list-marker-value      remark-lint
-        35:5  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
-        38:1  warning  Remove 1 line before node                               no-consecutive-blank-lines     remark-lint
-   40:1-42:4  warning  Missing code-language flag                              fenced-code-flag               remark-lint
-  46:1-46:26  warning  Code blocks should be fenced                            code-block-style               remark-lint
-
-⚠ 15 warnings
+bad.md
+    7:1-7:43  warning  Heading levels should increment by one level at a time       heading-increment                 remark-lint
+    9:1-9:33  warning  Don’t use multiple top level headings (9:1)                  no-multiple-toplevel-headings     remark-lint
+  13:1-13:27  warning  Do not use headings with similar content per section (11:1)  no-duplicate-headings-in-section  remark-lint
+      15:104  warning  Line must be at most 80 characters                           maximum-line-length               remark-lint
+        18:5  warning  Incorrect list-item indent: remove 2 spaces                  list-item-indent                  remark-lint
+        26:4  warning  Incorrect list-item indent: remove 1 space                   list-item-indent                  remark-lint
+   30:1-30:8  warning  Marker style should be `-`                                   unordered-list-marker-style       remark-lint
+        30:4  warning  Incorrect list-item indent: remove 1 space                   list-item-indent                  remark-lint
+        34:5  warning  Incorrect list-item indent: remove 1 space                   list-item-indent                  remark-lint
+   35:1-35:9  warning  Marker should be `2`, was `1`                                ordered-list-marker-value         remark-lint
+        35:5  warning  Incorrect list-item indent: remove 1 space                   list-item-indent                  remark-lint
+        38:1  warning  Remove 1 line before node                                    no-consecutive-blank-lines        remark-lint
+   40:1-42:4  warning  Missing code-language flag                                   fenced-code-flag                  remark-lint
+  46:1-46:26  warning  Code blocks should be fenced                                 code-block-style                  remark-lint
+
+⚠ 14 warnings
diff --git a/docs/test/bad.md b/docs/test/bad.md
@@ -14,7 +14,7 @@ Used to test violations of style.
 
 BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
 
-BAD: List immedidately following text.
+BAD: List immediately following text.
 -   list
 
 BAD: One space indents in lists.
@@ -45,4 +45,4 @@ BAD: Indented code-block.
 
     # Indented code block
 
-BAD: Missing newline at end of file.
+BAD: Missing newline at end of file.
diff --git a/docs/test/good.expected.md b/docs/test/good.expected.md
@@ -4,13 +4,30 @@ Used to test style.
 
 ## GOOD: One level step down headings.
 
-<!--lint disable no-duplicate-headings -->
+<!--lint disable no-duplicate-headings-in-section -->
 
 ### GOOD: Repeated Content when rule is disabled
 
 ### GOOD: Repeated Content when rule is disabled
 
-<!--lint enable no-duplicate-headings -->
+<!--lint enable no-duplicate-headings-in-section -->
+
+## GOOD: Section with subsections that duplicate
+
+This section has subsections that contain identical headers (steps) which
+should be allowed by `no-duplicate-headings-in-section`
+
+### GOOD: Section A
+
+#### GOOD: Step 1
+
+#### GOOD: Step 2
+
+### GOOD: Section B
+
+#### GOOD: Step 1
+
+#### GOOD: Step 2
 
 GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
 
@@ -28,4 +45,4 @@ GOOD: Fenced code-blocks with langauge.
 ```python
 print 'Hello Mobify'
 ```
-docs/test/good.md: no issues found
+good.md: no issues found
diff --git a/docs/test/good.md b/docs/test/good.md
@@ -4,13 +4,30 @@ Used to test style.
 
 ## GOOD: One level step down headings.
 
-<!--lint disable no-duplicate-headings -->
+<!--lint disable no-duplicate-headings-in-section -->
 
 ### GOOD: Repeated Content when rule is disabled
 
 ### GOOD: Repeated Content when rule is disabled
 
-<!--lint enable no-duplicate-headings -->
+<!--lint enable no-duplicate-headings-in-section -->
+
+## GOOD: Section with subsections that duplicate
+
+This section has subsections that contain identical headers (steps) which
+should be allowed by `no-duplicate-headings-in-section`
+
+### GOOD: Section A
+
+#### GOOD: Step 1
+
+#### GOOD: Step 2
+
+### GOOD: Section B
+
+#### GOOD: Step 1
+
+#### GOOD: Step 2
 
 GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
 
diff --git a/docs/test/test.sh b/docs/test/test.sh
@@ -5,13 +5,32 @@
 # The result of running our remark configuration on them is commited as
 # `.expected` files. If we change our configuration, a new output will be
 # expected and these files must be re-generated.
-NPM_BIN=$(npm bin)
+
 TEST_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+LINT_MD="$TEST_DIR/../bin/lint-md"
 
 # Re-generate `.expected` files with current configuration.
-# "$NPM_BIN/remark" "$TEST_DIR/good.md" --no-color > "$TEST_DIR/good.expected.md" 2>&1
-# "$NPM_BIN/remark" "$TEST_DIR/bad.md" --no-color > "$TEST_DIR/bad.expected.md" 2>&1
+#"$LINT_MD" "$TEST_DIR/good.md" --no-color > "$TEST_DIR/good.expected.md" 2>&1
+#"$LINT_MD" "$TEST_DIR/bad.md" --no-color > "$TEST_DIR/bad.expected.md" 2>&1
+#"$LINT_MD" "$TEST_DIR/a-bad-filename.md" --no-color > "$TEST_DIR/a-bad-filename.expected.md" 2>&1
 
 # Compare remark output with expected output. Fail on diff.
-diff <("$NPM_BIN/remark" "$TEST_DIR/good.md" --no-color 2>&1) "$TEST_DIR/good.expected.md"
-diff <("$NPM_BIN/remark" "$TEST_DIR/bad.md" --no-color 2>&1) "$TEST_DIR/bad.expected.md"
+echo "Testing good.md ..."
+diff <("$LINT_MD" "$TEST_DIR/good.md" --no-color 2>&1) "$TEST_DIR/good.expected.md"
+EXIT_GOOD=$?
+
+echo "Testing bad.md ..."
+diff <("$LINT_MD" "$TEST_DIR/bad.md" --no-color 2>&1) "$TEST_DIR/bad.expected.md"
+EXIT_BAD=$?
+
+echo "Testing a-bad-filename.expected.md ..."
+diff <("$LINT_MD" "$TEST_DIR/a-bad-filename.md" --no-color 2>&1) "$TEST_DIR/a-bad-filename.expected.md"
+EXIT_BAD_FILENAME=$?
+
+# Fail if either diff failed.
+# This if will fall apart quickly as we add more test cases.
+# Need to consider some type of looping, etc possibly.
+if [ "$EXIT_GOOD" -ne "0" ] || [ "$EXIT_BAD" -ne "0" ] || [ "$EXIT_BAD_FILENAME" -ne "0" ]; then
+    echo "One or more tests failed!"
+    exit 1
+fi
diff --git a/package.json b/package.json
@@ -16,11 +16,11 @@
   },
   "homepage": "https://github.com/mobify/mobify-code-style",
   "scripts": {
-    "test": "bash docs/test/test.sh"
+    "test": "cd docs/test; bash test.sh"
   },
   "dependencies": {
-    "remark-cli": "2.0.0",
-    "remark-lint": "5.0.1",
+    "remark-cli": "2.1.0",
+    "remark-lint": "5.2.0",
     "remark-preset-lint-recommended": "1.0.0"
   }
 }
