exclude auto-generated contents from docs/index.md; closes #3713

.gitignore

@@ -1,6 +1,7 @@
 # Mocha-specific
 docs/_site
 docs/_dist
+docs/index.md.tmp
 mocha.js
 .karma/
 !lib/mocha.js

docs/index.md

@@ -51,37 +51,6 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js][] and in
 ## Table of Contents
 
 <!-- AUTO-GENERATED-CONTENT:START (toc:maxdepth=2&bullets=-) -->
-
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Run Cycle Overview](#run-cycle-overview)
-- [Detects Multiple Calls to `done()`](#detects-multiple-calls-to-done)
-- [Assertions](#assertions)
-- [Asynchronous Code](#asynchronous-code)
-- [Synchronous Code](#synchronous-code)
-- [Arrow Functions](#arrow-functions)
-- [Hooks](#hooks)
-- [Pending Tests](#pending-tests)
-- [Exclusive Tests](#exclusive-tests)
-- [Inclusive Tests](#inclusive-tests)
-- [Retry Tests](#retry-tests)
-- [Dynamically Generating Tests](#dynamically-generating-tests)
-- [Timeouts](#timeouts)
-- [Diffs](#diffs)
-- [Command-Line Usage](#command-line-usage)
-- [Interfaces](#interfaces)
-- [Reporters](#reporters)
-- [Running Mocha in the Browser](#running-mocha-in-the-browser)
-- [Desktop Notification Support](#desktop-notification-support)
-- [Configuring Mocha (Node.js)](#configuring-mocha-nodejs)
-- [`mocha.opts`](#mochaopts)
-- [The `test/` Directory](#the-test-directory)
-- [Error Codes](#error-codes)
-- [Editor Plugins](#editor-plugins)
-- [Examples](#examples)
-- [Testing Mocha](#testing-mocha)
-- [More Information](#more-information)
-
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ## Installation
@@ -814,88 +783,6 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
 ## Command-Line Usage
 
 <!-- AUTO-GENERATED-CONTENT:START (usage:executable=bin/mocha) -->
-
-```plain
-
-mocha [spec..]
-
-Run tests with Mocha
-
-Commands
-  mocha debug [spec..]  Run tests with Mocha                           [default]
-  mocha init <path>     create a client-side Mocha setup at <path>
-
-Rules & Behavior
-  --allow-uncaught           Allow uncaught errors to propagate        [boolean]
-  --async-only, -A           Require all tests to use a callback (async) or
-                             return a Promise                          [boolean]
-  --bail, -b                 Abort ("bail") after first test failure   [boolean]
-  --check-leaks              Check for global variable leaks           [boolean]
-  --delay                    Delay initial execution of root suite     [boolean]
-  --exit                     Force Mocha to quit after tests complete  [boolean]
-  --forbid-only              Fail if exclusive test(s) encountered     [boolean]
-  --forbid-pending           Fail if pending test(s) encountered       [boolean]
-  --global, --globals        List of allowed global variables            [array]
-  --retries                  Retry failed tests this many times         [number]
-  --slow, -s                 Specify "slow" test threshold (in milliseconds)
-                                                          [number] [default: 75]
-  --timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
-                                                        [number] [default: 2000]
-  --ui, -u                   Specify user interface    [string] [default: "bdd"]
-
-Reporting & Output
-  --color, -c, --colors                     Force-enable color output  [boolean]
-  --diff                                    Show diff on failure
-                                                       [boolean] [default: true]
-  --full-trace                              Display full stack traces  [boolean]
-  --growl, -G                               Enable Growl notifications [boolean]
-  --inline-diffs                            Display actual/expected differences
-                                            inline within each string  [boolean]
-  --reporter, -R                            Specify reporter to use
-                                                      [string] [default: "spec"]
-  --reporter-option, --reporter-options,    Reporter-specific options
-  -O                                        (<k=v,[k1=v1,..]>)           [array]
-
-Configuration
-  --config   Path to config file                    [default: (nearest rc file)]
-  --opts     Path to `mocha.opts`        [string] [default: "./test/mocha.opts"]
-  --package  Path to package.json for config                            [string]
-
-File Handling
-  --exclude                        Ignore file(s) or glob pattern(s)
-                                                       [array] [default: (none)]
-  --extension, --watch-extensions  File extension(s) to load and/or watch
-                                                           [array] [default: js]
-  --file                           Specify file(s) to be loaded prior to root
-                                   suite execution     [array] [default: (none)]
-  --recursive                      Look for tests in subdirectories    [boolean]
-  --require, -r                    Require module      [array] [default: (none)]
-  --sort, -S                       Sort test files                     [boolean]
-  --watch, -w                      Watch files in the current working directory
-                                   for changes                         [boolean]
-
-Test Filters
-  --fgrep, -f   Only run tests containing this string                   [string]
-  --grep, -g    Only run tests matching this string or regexp           [string]
-  --invert, -i  Inverts --grep and --fgrep matches                     [boolean]
-
-Positional Arguments
-  spec  One or more files, directories, or globs to test
-                                                    [array] [default: ["test/"]]
-
-Other Options
-  --help, -h     Show usage information & exit                         [boolean]
-  --version, -V  Show version number & exit                            [boolean]
-  --interfaces   List built-in user interfaces & exit                  [boolean]
-  --reporters    List built-in reporters & exit                        [boolean]
-
-Mocha Resources
-    Chat: https://gitter.im/mochajs/mocha
-  GitHub: https://github.com/mochajs/mocha.git
-    Docs: https://mochajs.org/
-
-```
-
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ### `--allow-uncaught`
@@ -1893,8 +1780,5 @@ or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js).
 [yargs-configobject-extends]: http://yargs.js.org/docs/#api-configobject-extends-keyword
 [zsh-globbing]: http://zsh.sourceforge.net/Doc/Release/Expansion.html#Recursive-Globbing
 
-<!-- AUTO-GENERATED-CONTENT:START (manifest:template=[Gitter]: ${gitter}) -->
-
-[gitter]: https://gitter.im/mochajs/mocha
-
+<!-- AUTO-GENERATED-CONTENT:START (manifest:template=[gitter]: ${gitter}) -->
 <!-- AUTO-GENERATED-CONTENT:END -->

package-scripts.js

@@ -270,20 +270,21 @@ module.exports = {
         description: 'Build documentation'
       },
       prebuild: {
-        script: 'rimraf docs/_dist docs/_site && nps docs.preprocess',
+        script:
+          'shx cp docs/index.md docs/index.md.tmp && rimraf docs/_dist docs/_site && nps docs.preprocess',
         description: 'Prepare system for doc building',
         hiddenFromHelp: true
       },
       postbuild: {
         script:
-          'buildProduction docs/_site/index.html --outroot docs/_dist --canonicalroot https://mochajs.org/ --optimizeimages --svgo --inlinehtmlimage 9400 --inlinehtmlscript 0 --asyncscripts && cp docs/_headers docs/_dist/_headers && node scripts/netlify-headers.js >> docs/_dist/_headers',
+          'buildProduction docs/_site/index.html --outroot docs/_dist --canonicalroot https://mochajs.org/ --optimizeimages --svgo --inlinehtmlimage 9400 --inlinehtmlscript 0 --asyncscripts && cp docs/_headers docs/_dist/_headers && node scripts/netlify-headers.js >> docs/_dist/_headers && shx rm docs/index.md.tmp',
         description: 'Post-process docs after build',
         hiddenFromHelp: true
       },
       preprocess: {
         default: {
           script:
-            'md-magic --config ./scripts/markdown-magic.config.js --path docs/index.md',
+            'md-magic --config ./scripts/markdown-magic.config.js --path docs/index.md.tmp',
           description: 'Preprocess documentation',
           hiddenFromHelp: true
         },

package.json

@@ -562,6 +562,7 @@
     "remark-inline-links": "^3.1.2",
     "rewiremock": "^3.12.3",
     "rimraf": "^2.5.2",
+    "shx": "^0.3.2",
     "sinon": "^7.2.4",
     "strip-ansi": "^5.0.0",
     "svgo": "^1.1.1",