fix local documentation problems; closes #3157 [ci skip]

- update `Gemfile.lock`
- rename `prebuild-docs.js` to `docs-update-toc.js`
- fix `buildDocs`	and `serveDocs` options and ensure TOC is updated
- trim extra newlines from EOF in `index.md` after TOC update is run

Gemfile.lock

@@ -1,4 +1,5 @@
 GEM
+  remote: https://rubygems.org/
   specs:
     addressable (2.5.2)
       public_suffix (>= 2.0.2, < 4.0)

package.json

@@ -304,9 +304,10 @@
     "test": "make clean && make test",
     "prepublishOnly": "npm test && make clean && make mocha.js",
     "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"
+    "prebuildDocs": "node scripts/docs-update-toc.js",
+    "buildDocs": "bundle exec jekyll build --source ./docs --destination ./docs/_site --config ./docs/_config.yml --safe --drafts",
+    "prewatchDocs": "node scripts/docs-update-toc.js",
+    "watchDocs": "bundle exec jekyll serve --source ./docs --destination ./docs/_site --config ./docs/_config.yml --safe --drafts --watch"
   },
   "dependencies": {
     "browser-stdout": "1.3.0",

scripts/pre-build-docs.js → scripts/docs-update-toc.js

@@ -24,8 +24,10 @@ fs.createReadStream(docsFilepath)
   .on('close', () => {
     console.log('Done.');
   })
-  .pipe(utils.concat(
-    input => fs.writeFileSync(docsFilepath, toc.insert(String(input), {
+  .pipe(utils.concat(input => {
+    const output = toc.insert(String(input), {
       bullets: '-',
       maxdepth: 2
-    }))));
+    }).replace(/\n\n$/, '\n');
+    return fs.writeFileSync(docsFilepath, output);
+  }));