lint Markdown; closes #3172

- add [markdownlint-cli](https://npm.im/markdownlint-cli)
- lint all Markdown files
- add some rules to `.markdownlintrc`

.editorconfig

@@ -13,6 +13,3 @@ indent_size = 2
 
 [Makefile]
 indent_style = tab
-
-[*.md]
-trim_trailing_whitespace = false

.github/CODE_OF_CONDUCT.md

@@ -1,30 +1,35 @@
 # Mocha Code of Conduct
 
 ## Be friendly and patient
+
 We understand that everyone has different levels of experience or knowledge in many diverse fields, be it technical or
 non-technical in nature. We also have areas of knowledge we are eager to expand; we want to be a community where people
 can not only contribute, but feel comfortable to ask questions as well and learn along the way. If someone says something
 wrong, or says something accidentally offensive, respond with patience and try to keep it polite and civil. Remember that
 we all were newbies at one point.
 
 ## Be welcoming
+
 We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not
 limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class,
 educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief,
 religion, and mental and physical ability.
 
 ## Be considerate
+
 Your work will be used by other people, and you in turn will depend on the work of others. Any decision you make will affect
 users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide
 community, so you might not be communicating in someone else’s primary language.
 
 ## Be respectful
+
 Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all
 experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important
 to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the JS Foundation
 community should be respectful when dealing with other members as well as with people outside the JS Foundation community.
 
 ## Be careful in the words that you choose
+
 We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put
 down other participants. Harassment and other exclusionary behavior aren’t acceptable. This includes, but is not limited to:
 
@@ -38,6 +43,7 @@ down other participants. Harassment and other exclusionary behavior aren’t acc
 * Repeated harassment of others. In general, if someone asks you to stop, then stop.
 
 ## When we disagree, try to understand why
+
 Disagreements, both social and technical, happen all the time and JS Foundation projects are no exception. It is important
 that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of the JS
 Foundation comes from its varied community, people from a wide range of backgrounds. Different people have different
@@ -48,4 +54,5 @@ and learning from mistakes.
 Original text courtesy of the Speak Up! project and Django Project.
 
 ## QUESTIONS?
+
 If you have questions, please see the FAQ. If that doesn’t answer your questions, feel free to email [email protected].

.github/CONTRIBUTING.md

@@ -40,35 +40,35 @@ We ask you please keep these goals in mind when making or proposing changes.
 
 Follow these steps to get going.  If you are having trouble, don't be afraid to [ask for help](#got-a-question).
 
-1.  [Install Node.js 4.x or newer](https://nodejs.org/download).
-1.  Install [GNU Make](https://www.gnu.org/software/make/) or equivalent.
-1.  Follow [Github's documentation](https://help.github.com/articles/fork-a-repo/) on setting up Git, forking and cloning.
-1.  Create a new branch in your working copy.  Give your branch a descriptive name, such as `issue/12345`: `git checkout -b issue/12345`.
-1.  Execute `npm install` to install the development dependencies.
-1.  Make your changes and add them via `git add`.
-  - **Do not modify** the root `mocha.js` file directly; it is automatically generated.
-  - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js` if your changes are browser-specific.
-  - Please add unit and/or integration tests (depending on the nature of your changes).
-  - Keep your PR focused.  Don't fix two things at once, or make formatting changes alongside bug fixes.
-1.  Before committing, run `npm test`.
-  - This will run unit tests, Node.js and browser integration tests, and lint the source code.
-  - The "browser" tests use Mocha to test itself; it will rebuild the root `mocha.js` file with your changes.
-  - **Please avoid committing changes to `mocha.js`**.
-  - Ultimately, your pull request will be built on our continuous integration servers ([Travis CI](https://travis-ci.org/mochajs/mocha) and [AppVeyor](https://ci.appveyor.com/project/boneskull/mocha)).  The first step to ensuring these checks pass is to test on your own machine.
-1.  Commit your changes.
-  - Use a brief message on the first line, referencing a relevant issue (e.g. `#12345`).
-  - Add detail in subsequent lines.
-1.  Push your changes to your fork.
-1.  Navigate to the source repository.  You should see a notification about your recent changes in your fork's branch, with a button to create a pull request.  Click it.
-1.  Describe your changes in detail here.  Once you're satisfied, submit the form.
-  - *PRO TIP*: If you've used a multi-line commit message, Github will pre-fill the PR's description with it.
-1.  If you have not signed our Contributor License Agreement, a friendly robot will prompt you to do so.  A [CLA](https://cla.js.foundation/mochajs/mocha) (electronic) signature is **required** for all contributions of code to Mocha.
-1.  CI will run against your changes.
-  - If the changes fail the checks, you will need to address those before merging.
-  - You don't need to make a new PR to make changes.  Instead, commit on top of your changes, and push these to your fork's branch.  The PR will be updated, and CI will re-run.
-  - Github will indicate if there's a conflict.  If this happens, you will need to [rebase](https://help.github.com/articles/about-git-rebase/) your branch onto the `master` branch of the source repository.  *Don't merge.*
-  - It's no longer necessary to "squash" your changes.
-1.  Be patient while your PR is reviewed.  This can take awhile ([why?](https://github.com/orgs/mochajs/projects/4)).  We may request changes; don't be afraid to question them.
+1. [Install Node.js 4.x or newer](https://nodejs.org/download).
+1. Install [GNU Make](https://www.gnu.org/software/make/) or equivalent.
+1. Follow [Github's documentation](https://help.github.com/articles/fork-a-repo/) on setting up Git, forking and cloning.
+1. Create a new branch in your working copy.  Give your branch a descriptive name, such as `issue/12345`: `git checkout -b issue/12345`.
+1. Execute `npm install` to install the development dependencies.
+1. Make your changes and add them via `git add`.
+    - **Do not modify** the root `mocha.js` file directly; it is automatically generated.
+    - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js` if your changes are browser-specific.
+    - Please add unit and/or integration tests (depending on the nature of your changes).
+    - Keep your PR focused.  Don't fix two things at once, or make formatting changes alongside bug fixes.
+1. Before committing, run `npm test`.
+    - This will run unit tests, Node.js and browser integration tests, and lint the source code.
+    - The "browser" tests use Mocha to test itself; it will rebuild the root `mocha.js` file with your changes.
+    - **Please avoid committing changes to `mocha.js`**.
+    - Ultimately, your pull request will be built on our continuous integration servers ([Travis CI](https://travis-ci.org/mochajs/mocha) and [AppVeyor](https://ci.appveyor.com/project/boneskull/mocha)).  The first step to ensuring these checks pass is to test on your own machine.
+1. Commit your changes.
+    - Use a brief message on the first line, referencing a relevant issue (e.g. `#12345`).
+    - Add detail in subsequent lines.
+1. Push your changes to your fork.
+1. Navigate to the source repository.  You should see a notification about your recent changes in your fork's branch, with a button to create a pull request.  Click it.
+1. Describe your changes in detail here.  Once you're satisfied, submit the form.
+    - *PRO TIP*: If you've used a multi-line commit message, Github will pre-fill the PR's description with it.
+1. If you have not signed our Contributor License Agreement, a friendly robot will prompt you to do so.  A [CLA](https://cla.js.foundation/mochajs/mocha) (electronic) signature is **required** for all contributions of code to Mocha.
+1. CI will run against your changes.
+    - If the changes fail the checks, you will need to address those before merging.
+    - You don't need to make a new PR to make changes.  Instead, commit on top of your changes, and push these to your fork's branch.  The PR will be updated, and CI will re-run.
+    - Github will indicate if there's a conflict.  If this happens, you will need to [rebase](https://help.github.com/articles/about-git-rebase/) your branch onto the `master` branch of the source repository.  *Don't merge.*
+    - It's no longer necessary to "squash" your changes.
+1. Be patient while your PR is reviewed.  This can take awhile ([why?](https://github.com/orgs/mochajs/projects/4)).  We may request changes; don't be afraid to question them.
 
 ## :angel: I Just Want To Help
 

.github/ISSUE_TEMPLATE.md

@@ -4,16 +4,18 @@ For more, check out the Mocha Gitter chat room: https://gitter.im/mochajs/mocha
 -->
 
 ### Prerequisites
+
 <!--
 Place an `x` between the square brackets on the lines below for every satisfied prerequisite.
 -->
-* [ ] Checked that your issue isn't already filed by cross referencing [issues with the `common mistake` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Acommon-mistake%20)
-* [ ] Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code.
-* [ ] 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself
-* [ ] Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with:
-`node node_modules/.bin/mocha --version`(Local) and `mocha --version`(Global). We recommend avoiding the use of globally installed Mocha.
+
+- [ ] Checked that your issue isn't already filed by cross referencing [issues with the `common mistake` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Acommon-mistake%20)
+- [ ] Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code.
+- [ ] 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself
+- [ ] Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with: `node node_modules/.bin/mocha --version`(Local) and `mocha --version`(Global). We recommend avoiding the use of globally installed Mocha.
 
 ### Description
+
 <!--
 [Description of the issue]
 -->
@@ -32,18 +34,19 @@ on how to create a minimal, complete, and verifiable example.
 **Reproduces how often:** [What percentage of the time does it reproduce?]
 
 ### Versions
-<!--
- If applicable, please specify:
- * The output of `mocha --version` and `node node_modules/.bin/mocha --version`:
- * The output of `node --version`:
- * The version and architecture of your operating system:
- * Your shell (bash, zsh, PowerShell, cmd, etc.):
- * Your browser and version (if running browser tests):
- * Any other third party Mocha related modules (with versions):
- * The code transpiler being used:
--->
+
+<!-- If applicable, please specify: -->
+
+- The output of `mocha --version` and `node node_modules/.bin/mocha --version`:
+- The output of `node --version`:
+- The version and architecture of your operating system:
+- Your shell (bash, zsh, PowerShell, cmd, etc.):
+- Your browser and version (if running browser tests):
+- Any other third party Mocha related modules (with versions):
+- The code transpiler being used:
 
 ### Additional Information
+
 <!--
 Any additional information, configuration or data that might be necessary to reproduce the issue.
 -->

.markdownlint.json

@@ -0,0 +1,10 @@
+{
+  "no-inline-html": false,
+  "line-length": false,
+  "no-trailing-punctuation": false,
+  "no-duplicate-header": false,
+  "first-header-h1": false,
+  "first-line-h1": false,
+  "commands-show-output": false,
+  "single-h1": false
+}