Auto lint content (#492)

* Auto fix linting in documentation Markdown on commit

* Auto lint content

.gitignore

@@ -7,3 +7,4 @@ npm-debug.log*
 yarn-error.log
 dist-es5-module/
 tmp
+docs/.textlintcache

docs/.textlintrc.js

@@ -1,25 +1,38 @@
 /* eslint-disable import/no-commonjs */
-module.exports = {
-  rules: {
-    alex: {
-      allow: ['color', 'hook', 'host-hostess', 'itch'],
-    },
-    'common-misspellings': true,
-    'en-capitalization': true,
-    'stop-words': {
-      exclude: [
-        'relative to', // We need to talk about links "relative to the root",
-        'pick out', // Needed word, not to clumsy
-        'encounter', // Needed word, not to clumsy
-      ],
-    },
-    terminology: {
-      defaultTerms: false,
-      terms: `${__dirname}/.textlint.terms.json`,
-    },
-    'write-good': {
-      passive: true,
-      severity: 'warning',
-    },
+const _ = require('lodash');
+const textlintMode = process.env.TEXTLINT_MODE;
+
+const allRules = {
+  alex: {
+    allow: ['color', 'hook', 'host-hostess', 'itch'],
+  },
+  'common-misspellings': true,
+  'en-capitalization': true,
+  'stop-words': {
+    exclude: [
+      'relative to', // We need to talk about links "relative to the root",
+      'pick out', // Needed word, not to clumsy
+      'encounter', // Needed word, not to clumsy
+    ],
+  },
+  terminology: {
+    defaultTerms: false,
+    terms: `${__dirname}/.textlint.terms.json`,
+  },
+  'write-good': {
+    passive: true,
+    severity: 'warning',
   },
 };
+
+// Not all rules are automatically fixable, so when running `yarn run
+// lint:md:fix`, we only run the one that can be fixed.
+const fixableRules = _.pick(allRules, [
+  'common-misspellings',
+  'en-capitalization',
+  'terminology',
+]);
+
+module.exports = {
+  rules: textlintMode === 'fix' ? fixableRules : allRules,
+};

docs/package.json

@@ -9,7 +9,8 @@
     "lint:css": "./scripts/lint-css",
     "lint:md": "./scripts/lint-md",
     "lint:md:fix": "./scripts/lint-md-fix",
-    "prepush": "./scripts/prepush",
+    "precommit": "./scripts/precommit",
+    "prepush": "yarn lint",
     "serve": "babel-node ./scripts/serve.js"
   },
   "devDependencies": {

docs/scripts/lint-md-fix

@@ -14,15 +14,18 @@ REMARK_MODE=fix \
 
 # We then check the actual natural language content of the file, to fix
 # misspellings, punctuation and other fixable issues.
-textlint \
+TEXTLINT_MODE=fix textlint \
   --fix \
+  --cache \
   ./*.md \
-  ./src/*.md 
+  ./src/*.md \
+  1>/dev/null
 
 # Finally, we'll run everything through prettier to make sure all files are
 # formatted the same way. This will remove trailing spaces, fit all content
 # under 80 char long lines, etc
 prettier \
+  --loglevel error \
   --write \
   ./*.md \
   ./src/*.md

docs/scripts/precommit

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+
+# This script is run before each commit on the repo and will try to fix linting
+# issues of the documentation.
+
+# This is run from ./docs folder, we need to go back to the git root to run the
+# git methods
+cd ../ || exit 1
+
+# We only run the auto-fix when changes are actually made to markdown files
+git diff --name-status master | grep '^\(.*\)docs/\(.*\).md$' 1>/dev/null
+DOCS_FOLDER_HAS_CHANGED=$?
+if [ "$DOCS_FOLDER_HAS_CHANGED" = "1" ]; then
+  exit 0
+fi
+
+echo "Markdown documentation updated."
+echo "Running auto-lint..."
+cd ./docs || exit 1
+yarn run lint:md:fix
+
+cd ../ || exit 1
+git add ./docs/**/*.md

docs/src/how-does-it-work.md

@@ -12,9 +12,8 @@ Search-UI in your frontend. It is as simple as copying and pasting a snippet.
 ### You apply
 
 The first thing you'll need to do is apply for DocSearch by filling out the form
-on this page (double check first that you qualify). We are
-receiving a lot of requests, so this form makes sure we won't be forgetting
-anyone.
+on this page (double check first that you qualify). We are receiving a lot of
+requests, so this form makes sure we won't be forgetting anyone.
 
 We guarantee that we will answer every request, but as we receive a lot of
 applications, please give us a couple of days to get back to you :)

docs/src/tips.md

@@ -116,8 +116,7 @@ Duplicates introduce noise and mislead users. This is why you should always
 focus on the relevant content and avoid duplicating content within your site
 (for example landing page which contains all information, summing up, etc.). In
 cases where the duplicates's existence is expected since it belongs to another
-dataset (for example a different version), you should use
-[facets](https://www.algolia.com/doc/guides/searching/faceting/).
+dataset (for example a different version), you should use [facets][3].
 
 ## Conciseness
 
@@ -129,3 +128,4 @@ search for technical documentation][2].
 [1]: https://www.sitemaps.org/index.html
 [2]:
   https://blog.algolia.com/how-to-build-a-helpful-search-for-technical-documentation-the-laravel-example/
+[3]: https://www.algolia.com/doc/guides/searching/faceting/