migrate mochajs.github.io into mocha; closes #2987 [ci skip]

- some jekyll tweaks were needed; we can no longer consume the
  `github-pages` gem apparently since they added support for themes
- added `markdown-toc` dev dep to build the toc
- added `buildDocs` and `serveDocs` scripts
- miraculously avoided monkeying with the content itself

Signed-off-by: Christopher Hiller <boneskull@boneskull.com>

.gitignore

@@ -15,3 +15,4 @@ coverage/
 yarn.lock
 package-lock.json
 mocha.js
+docs/_site

Gemfile

@@ -0,0 +1,3 @@
+
+# Added at 2017-12-05 23:01:55 -0800 by boneskull:
+gem "jekyll", "~> 3.6"

Gemfile.lock

@@ -0,0 +1,50 @@
+GEM
+  specs:
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    colorator (1.1.0)
+    ffi (1.9.18)
+    forwardable-extended (2.6.0)
+    jekyll (3.6.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 1.1)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 3)
+      safe_yaml (~> 1.0)
+    jekyll-sass-converter (1.5.0)
+      sass (~> 3.4)
+    jekyll-watch (1.5.1)
+      listen (~> 3.0)
+    kramdown (1.14.0)
+    liquid (4.0.0)
+    listen (3.0.8)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    mercenary (0.3.6)
+    pathutil (0.16.0)
+      forwardable-extended (~> 2.6)
+    public_suffix (3.0.0)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rouge (2.2.1)
+    safe_yaml (1.0.4)
+    sass (3.5.3)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jekyll (~> 3.6)
+
+BUNDLED WITH
+   1.16.0

package.json

@@ -303,7 +303,10 @@
     "lint": "eslint . bin/*",
     "test": "make clean && make test",
     "prepublishOnly": "npm test && make clean && make mocha.js",
-    "coveralls": "nyc report --reporter=text-lcov | coveralls"
+    "coveralls": "nyc report --reporter=text-lcov | coveralls",
+    "prebuildDocs": "node scripts/pre-build-docs.js",
+    "buildDocs": "bundle exec jekyll build --source docs --destination docs/_site --layouts docs/_layouts --safe --drafts",
+    "serveDocs": "bundle exec jekyll serve --config docs/_config.yml --safe --drafts --watch"
   },
   "dependencies": {
     "browser-stdout": "1.3.0",
@@ -340,6 +343,7 @@
     "karma-mocha-reporter": "^2.2.4",
     "karma-phantomjs-launcher": "^1.0.4",
     "karma-sauce-launcher": "^1.2.0",
+    "markdown-toc": "^1.2.0",
     "nyc": "^11.2.1",
     "rimraf": "^2.5.2",
     "through2": "^2.0.1",

scripts/.eslintrc.yaml

@@ -0,0 +1,2 @@
+parserOptions:
+  ecmaVersion: 2017

scripts/pre-build-docs.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * The CLI included with markdown-toc doesn't support `bullets`
+ * and `maxdepth` options, so that's why this exists.
+ */
+
+'use strict';
+
+const toc = require('markdown-toc');
+const utils = require('markdown-toc/lib/utils');
+const fs = require('fs');
+const path = require('path');
+
+const docsFilepath = path.join(__dirname, '..', 'docs', 'index.md');
+
+console.log('Updating TOC...');
+
+fs.createReadStream(docsFilepath)
+  .on('error', err => {
+    console.log(err);
+    process.exit(1);
+  })
+  .on('close', () => {
+    console.log('Done.');
+  })
+  .pipe(utils.concat(
+    input => fs.writeFileSync(docsFilepath, toc.insert(String(input), {
+      bullets: '-',
+      maxdepth: 2
+    }))));