chore(docs): Documentation Linting and TOC generation (videojs#3841)

Use remark to lint and generate TOC for markdown files.

.github/ISSUE_TEMPLATE.md

@@ -4,7 +4,6 @@ Include a [reduced test case](https://css-tricks.com/reduced-test-cases/), we ha
 
 ## Steps to reproduce
 Explain in detail the exact steps necessary to reproduce the issue.
-
 1.
 2.
 3.

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,7 +3,6 @@ Please describe the change as necessary.
 If it's a feature or enhancement please be as detailed as possible.
 If it's a bug fix, please link the issue that it fixes or describe the bug in as much detail.
 
-
 ## Specific Changes proposed
 Please list the specific changes involved in this pull request.
 

.remarkignore

@@ -0,0 +1 @@
+CHANGELOG.md

.remarkrc.js

@@ -0,0 +1,84 @@
+var remarkrc = {
+  settings: {
+    bullet: '*',
+    fence: '`',
+    strong: '*',
+    emphasis: '_',
+    listItemIndent: 1,
+    incrementListMarker: false
+  },
+  plugins: {
+    'toc': {
+      tight: true
+    },
+  }
+};
+var args = process.argv;
+
+// only lint in non-output mode
+if (args.indexOf('-o') === -1 && args.indexOf('--output') === -1) {
+  remarkrc['validate-links'] = {};
+  remarkrc.plugins.lint = {
+    'blockquote-indentation': ['error', 2],
+    'checkbox-character-style': ['warn'],
+    'checkbox-content-indent': ['error'],
+    'code-block-style': ['error', 'fenced'],
+    'definition-case': ['off'],
+    'definition-spacing': ['error'],
+    'emphasis-marker': ['error', '_'],
+    'fenced-code-flag': ['error'],
+    'fenced-code-marker': ['error', '`'],
+    'file-extension': ['error'],
+    'final-definition': ['error'],
+    'final-newline': ['off'],
+    'first-heading-level': ['warn', 1],
+    'hard-break-spaces': ['off'],
+    'heading-increment': ['error'],
+    'heading-style': ['error', 'atx'],
+    'link-title-style': ['warn', '"'],
+    'list-item-bullet-indent': ['error'],
+    'list-item-content-indent': ['warn'],
+    'list-item-indent': ['error', 'space'],
+    'list-item-spacing': ['off'],
+    'maximum-heading-length': ['off'],
+    'maximum-line-length': ['off'],
+    'no-auto-link-without-protocol': ['error'],
+    'no-blockquote-without-caret': ['error'],
+    'no-consecutive-blank-lines': ['error'],
+    'no-duplicate-definitions': ['error'],
+    'no-duplicate-headings-in-section': ['error'],
+    'no-duplicate-headings': ['off'],
+    'no-emphasis-as-heading': ['error'],
+    'no-file-name-articles': ['off'],
+    'no-file-name-consecutive-dashes': ['off'],
+    'no-file-name-irregular-characters': ['warn', '\\.a-zA-Z0-9-_'],
+    'no-file-name-mixed-case': ['error'],
+    'no-file-name-outer-dashes': ['error'],
+    'no-heading-content-indent': ['error'],
+    'no-heading-indent': ['error'],
+    'no-heading-punctuation': ['off'],
+    'no-html': ['off'],
+    'no-inline-padding': ['error'],
+    'no-literal-urls': ['off'],
+    'no-missing-blank-lines': ['off'],
+    'no-multiple-toplevel-headings': ['error'],
+    'no-reference-like-url': ['error'],
+    'no-shell-dollars': ['error'],
+    'no-shortcut-reference-iamge': ['off'],
+    'no-shortcut-reference-link': ['off'],
+    'no-table-indentation': ['error'],
+    'no-tabs': ['error'],
+    'no-undefined-references': ['error'],
+    'no-unused-definitions': ['error'],
+    'ordered-list-marker-style': ['error', '.'],
+    'ordered-list-marker-value': ['error', 'one'],
+    'rule-style': ['error', '***'],
+    'strong-marker': ['error', '*'],
+    'table-cell-padding': ['warn', 'padded'],
+    'table-cell-alignment': ['warn'],
+    'table-pipes': ['warn'],
+    'unordered-list-marker-style': ['warn', '*']
+  };
+}
+
+module.exports = remarkrc;

COLLABORATOR_GUIDE.md

@@ -1,28 +1,24 @@
 # Collaborator Guide
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Issues and Pull Requests](#issues-and-pull-requests)
-- [Accepting changes](#accepting-changes)
-  - [Involving the TSC](#involving-the-tsc)
-- [Landing a PR](#landing-a-pr)
-  - [Landing a PR manually](#landing-a-pr-manually)
-    - [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
-    - [I just made a mistake](#i-just-made-a-mistake)
-      - [I accidentally pushed a broken commit or incorrect commit to master](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-master)
-      - [I lost changes](#i-lost-changes)
-      - [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
-- [video.js releases](#videojs-releases)
-  - [Getting dependencies](#getting-dependencies)
-    - [Install contrib](#install-contrib)
-    - [npm access](#npm-access)
-    - [GitHub personal access token](#github-personal-access-token)
-  - [Doing a release](#doing-a-release)
-- [Doc credit](#doc-credit)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+## Table of Contents
+
+* [Issues and Pull Requests](#issues-and-pull-requests)
+* [Accepting changes](#accepting-changes)
+  * [Involving the TSC](#involving-the-tsc)
+* [Landing a PR](#landing-a-pr)
+  * [Landing a PR manually](#landing-a-pr-manually)
+    * [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
+    * [I just made a mistake](#i-just-made-a-mistake)
+      * [I accidentally pushed a broken commit or incorrect commit to master](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-master)
+      * [I lost changes](#i-lost-changes)
+      * [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
+* [video.js releases](#videojs-releases)
+  * [Getting dependencies](#getting-dependencies)
+    * [Install contrib](#install-contrib)
+    * [npm access](#npm-access)
+    * [GitHub personal access token](#github-personal-access-token)
+  * [Doing a release](#doing-a-release)
+* [Doc credit](#doc-credit)
 
 ## Issues and Pull Requests
 
@@ -77,7 +73,7 @@ The footer should contain things like whether this is a breaking change or what
 
 Here's an example:
 
-```
+```commit
 fix(html5): a regression with html5 tech
 
 This is where you'd explain what the regression is.
@@ -90,87 +86,91 @@ Fixes #123
 _Optional:_ ensure you're not in a weird rebase or merge state:
 
 ```sh
-$ git am --abort
-$ git rebase --abort
+git am --abort
+git rebase --abort
 ```
 
 Checkout and update the master branch:
 
 ```sh
-$ git checkout master
-$ git remote update
-$ git rebase upstream/master
+git checkout master
+git remote update
+git rebase upstream/master
 ```
 
 Check out the PR:
 
 ```sh
-$ git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
-$ git checkout -t {{name of branch}}
+git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
+git checkout -t {{name of branch}}
 ```
 
 > For example:
+>
 > ```sh
-> $ git fetch upstream pull/123/head:gkatsev-html5-fix
-> $ git checkout -t gkatsev-html5-fix
+> git fetch upstream pull/123/head:gkatsev-html5-fix
+> git checkout -t gkatsev-html5-fix
 > ```
 
 _Optional:_ If necessary, rebase against master. If you have multiple features in the PR, [landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
 
 ```sh
-$ git rebase master
+git rebase master
 ```
 
 Fix up any issues that arise from the rebase, change back to the master branch and squash merge:
 
 ```sh
-$ git checkout master
-$ git merge --squash --no-commit gkatsev-html5-fix
+git checkout master
+git merge --squash --no-commit gkatsev-html5-fix
 ```
 
 The `--no-commit` tells git not to make a commit on your behalf. It does stage everything for you, so, you can instead it:
 
 ```sh
-$ git diff --cached
+git diff --cached
 ```
 
 Now get the author from the original commit:
 
 ```sh
-$ git log -n 1 --pretty=short gkatsev-html5-fix
+git log -n 1 --pretty=short gkatsev-html5-fix
 ```
+
 Which shows:
-```
-commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
-Author: Gary Katsevman <[email protected]>
 
-    Update TOC
+```txt
+  commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
+  Author: Gary Katsevman <[email protected]>
+
+      Update TOC
 ```
 
 Now you can commit the change the change with the author, following our commit guidelines
 
 ```sh
-$ git commit --author "Gary Katsevman <[email protected]>"
+git commit --author "Gary Katsevman <[email protected]>"
 ```
 
 Now that it's committed, push to master
 
 ```sh
-$ git push upstream master
+git push upstream master
 ```
 
 Congratulate yourself for a job well done and the contributor for having his change landed in master.
 
 #### Landing a PR manually with several changes
+
 Follow the same steps as before but when you rebase against master, you want to do an interactive rebase and then squash the changes into just a few commits.
 
 ```sh
-$ git rebase -i master
+git rebase -i master
 ```
 
 This will give you an output like the following:
 
-```
+```txt
 pick b4dc15d Update CONTRIBUTING.md with latest info
 pick 8592149 Add Dev certificate of origin
 pick 259dee6 Add grunt and doctoc npm scripts
@@ -201,10 +201,10 @@ pick 433c582 Update TOC
 Replace `pick` to `fixup` or `edit` depending on how you want the output to look. You can also re-order the commits, if necessary.
 
 > `fixup` will squash the commit it's infront of up into the commit above it
-
+>
 > `edit` will allow you to edit the commit message before continuing
 
-```
+```txt
 edit b4dc15d Update CONTRIBUTING.md with latest info
 fixup 8592149 Add Dev certificate of origin
 fixup f12af12 Add conventional-changelog-videojs link
@@ -216,17 +216,18 @@ edit 259dee6 Add grunt and doctoc npm scripts
 When you get to the edit commits, git will give more information, but you'd want to run ammend the current commit while following our commit guidelines
 
 ```sh
-$ git commit --amend
+git commit --amend
 ```
 
 After going through and making the commits you want, you want to change back to master and then rebase the branch onto master so we get a clean history
 
 ```sh
-$ git rebase gkatsev-html5-fix
+git rebase gkatsev-html5-fix
 ```
 
 This will put our two commits into master:
-```
+
+```txt
 b4dc15d chore(contributing.md): Update CONTRIBUTING.md with latest info <Gary Katsevman>
 259dee6 chore(package.json): Add grunt and doctoc npm scripts <Gary Katsevman>
 9e20386 v5.12.6 <Gary Katsevman>
@@ -253,7 +254,7 @@ This is a great time to discover that something is broken. Because it hasn't bee
 To do so, just reset the branch against master.
 
 ```sh
-$ git reset --hard upstream/master
+git reset --hard upstream/master
 ```
 
 ## video.js releases
@@ -295,7 +296,7 @@ After generating one, make sure to keep it safe because GitHub will not show the
 To do a release, check out the master branch
 
 ```sh
-$ git checkout master
+git checkout master
 ```
 
 Then run the contrib command to do the next release. Don't forget to provide your GitHub token so the GitHub release goes through.
@@ -312,7 +313,8 @@ After it's done, verify that the GitHub release has the correct changelog output
 
 This collaborator guide was heavily inspired by [node.js's guide](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md)
 
-
 [issue template]: /.github/ISSUE_TEMPLATE.md
+
 [pr template]: /.github/PULL_REQUEST_TEMPLATE.md
+
 [conventions]: https://github.com/videojs/conventional-changelog-videojs/blob/master/convention.md