Document Markdown linting

[apetro]

As demonstrated in #604 , it's quite possible to try to update e.g. the CHANGELOG.md and fail linting.

How again do I run this linting locally? Would it help any to document this or call out how to understand this by looking at .travis.yml, in CONTRIBUTING.md?

[ChristianMurphy]

npm run lint-md is the script

It could be helpful to call it out in the Travis CI script and CONTRIBUTING.md

[apetro]

Yup. I'm now four or five levels deep in yak shaving trying to get npm run lint-md to run locally. Apparently this requires remark? Which maybe I could install via Homebrew except Homebrew requires a later version of Ruby than I'm using? Which maybe I could install and switch to via rbenv? Except that fails in RDoc generation looking for some missing symbol called _utimensat?

Someday I'll get a new MacBook Pro and a fresh start at installing the universe.

[ChristianMurphy]

remark comes from the package.json.
If its not showing up, I'd recommend rm -rf node_modules && npm install.

[apetro]

Noting idea from #629 (comment) : Maybe even document how to get lint-on-commit-attempt working locally,

[ChristianMurphy]

Maybe even document how to get lint-on-commit-attempt working locally

Its worth trying, there are platform specific and hook specific edge cases to handle, that husky handles automatically, but may be challenging to capture in documentation.

ref: https://github.com/typicode/husky/blob/5e27cf888d5b0cebf5bb6bd9b1c2fb54911eb62b/src/utils/get-hook-script.js

[ChristianMurphy]

@apetro did #634 include the information you want to document here, or is additional documentation needed?

[apetro]

Pretty sure there's more to usefully say about Markdown linting. Including that we don't presently lint JS examples embedded therein but hope to eventually and so it'd be a fine thing to voluntarily lint this stuff now and here's how to do it, etc.