do not commit generated content to VCS; closes #3713 (#4289)

* do not commit generated content to VCS

This removes `markdown-magic` and replaces its functionality with the built-in data capabilities of 11ty.

The TOC, `--help` output, and source files are now all done via global data scripts in `docs/_data`.

When building documentation, we will no longer get changes to e.g., `docs/index.md` because of the automatically generated content.

* add inclusive language plugin to eleventy

Usage of the words as defined in options will result in a warning, and will not break the build.

Also: Eleventy should ignore the historical changelogs in `docs/changelogs`.

.eleventy.js

@@ -1,6 +1,14 @@
 'use strict';
 
 module.exports = function(eleventyConfig) {
+  eleventyConfig.addPlugin(
+    require('@11ty/eleventy-plugin-inclusive-language'),
+    {
+      words:
+        'simply,obviously,basically,of course,clearly,everyone knows,however,easy'
+    }
+  );
+
   eleventyConfig.addPassthroughCopy('docs/css');
   eleventyConfig.addPassthroughCopy('docs/js');
   eleventyConfig.addPassthroughCopy('docs/images');

.eslintrc.yml

@@ -36,6 +36,7 @@ overrides:
       - test/integration/options/watch.spec.js
       - test/integration/helpers.js
       - lib/growl.js
+      - docs/_data/**/*.js
     parserOptions:
       ecmaVersion: 2017
     env:

docs/.eleventyignore

@@ -4,3 +4,4 @@ LICENSE*
 .*
 _dist/
 example/
+changelogs/

docs/README.md

@@ -34,7 +34,7 @@ _So you wanna build the site?_
 cp: docs/_dist/_headers: No such file or directory
 ```
 
-- See `package-scripts.js` for details on what the builds are actually doing; especially see [markdown-magic](https://npm.im/markdown-magic) for how we're dynamically inserting information into `docs/index.md`.
+- See `package-scripts.js` for details on what the builds are actually doing.
 
 ## License
 

docs/_data/files.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const {resolve, relative, dirname} = require('path');
+const {readFileSync} = require('fs');
+
+const PROJECT_ROOT_DIR = resolve(__dirname, '..', '..');
+const FILES = [
+  {
+    slug: 'simplereporter',
+    path: require.resolve('../../test/integration/fixtures/simple-reporter.js'),
+    header: '// my-reporter.js'
+  }
+];
+
+const HEADER = '```js\n';
+const FOOTER = '```\n';
+
+const loadFile = (path, {header} = {}) => {
+  const relativeDir = relative(dirname(path), PROJECT_ROOT_DIR);
+  let content = readFileSync(path, 'utf-8');
+  // replace relative paths in `require()` to root with "mocha".
+  // might not work in the general case. not gonna parse an AST for this
+  // e.g. `require('../../lib/foo')` => `require('mocha/lib/foo')`
+  // also trim any trailing whitespace
+  content = content
+    .replace(
+      new RegExp(`require\\(['"]${relativeDir}(.*?)['"]\\)`, 'g'),
+      "require('mocha$1')"
+    )
+    .trim();
+  return `${HEADER}${header}\n\n${content}${FOOTER}`;
+};
+
+/**
+ * Loads files from disk (see `FILES` above) to be shown as data.
+ * Used for embedding sources directly into pages
+ */
+module.exports = () => {
+  const files = FILES.map(({path, header, slug}) => {
+    const content = loadFile(path, {header});
+    return {slug, content};
+  });
+  return files.reduce(
+    (files, {slug, content}) => ({
+      ...files,
+      [slug]: content
+    }),
+    {}
+  );
+};

docs/_data/toc.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const markdownToc = require('markdown-toc');
+const {readFileSync} = require('fs');
+const {resolve} = require('path');
+
+const IGNORED_HEADINGS_REGEXP = /Features|Table of Contents|Backers|Sponsors/i;
+const DOCUMENT_PATH = resolve(__dirname, '..', 'index.md');
+
+module.exports = () => {
+  const doc = readFileSync(DOCUMENT_PATH, 'utf-8');
+  return markdownToc(doc, {
+    slugify: require('uslug'),
+    firsth1: false,
+    bullets: '-',
+    maxdepth: 2,
+    // if filter is supplied, maxdepth is apparently ignored,
+    // so we have to do it ourselves.
+    filter: (str, ele) => ele.lvl < 2 && !IGNORED_HEADINGS_REGEXP.test(str)
+  }).content;
+};

docs/_data/usage.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const stripAnsi = require('strip-ansi');
+const {resolve} = require('path');
+const {execSync} = require('child_process');
+
+const executable = require.resolve('../../bin/mocha');
+const flag = '--help';
+
+/**
+ * Return the output of `mocha --help` for display
+ */
+module.exports = () => {
+  return stripAnsi(
+    String(
+      execSync(`"${process.execPath}" ${executable} ${flag}`, {
+        cwd: resolve(__dirname, '..')
+      })
+    ).trim()
+  );
+};

docs/api-tutorials/custom-reporter.md

@@ -6,70 +6,7 @@ For example, if `mocha-foo-reporter` was published to the npm registry, you coul
 
 If you're looking to get started quickly, here's an example of a custom reporter:
 
-<!-- AUTO-GENERATED-CONTENT:START (file:src=../../test/integration/fixtures/simple-reporter.js&header=// my-reporter.js)' -->
-
-```js
-// my-reporter.js
-'use strict';
-
-const Mocha = require('mocha');
-const {
-  EVENT_RUN_BEGIN,
-  EVENT_RUN_END,
-  EVENT_TEST_FAIL,
-  EVENT_TEST_PASS,
-  EVENT_SUITE_BEGIN,
-  EVENT_SUITE_END
-} = Mocha.Runner.constants;
-
-// this reporter outputs test results, indenting two spaces per suite
-class MyReporter {
-  constructor(runner) {
-    this._indents = 0;
-    const stats = runner.stats;
-
-    runner
-      .once(EVENT_RUN_BEGIN, () => {
-        console.log('start');
-      })
-      .on(EVENT_SUITE_BEGIN, () => {
-        this.increaseIndent();
-      })
-      .on(EVENT_SUITE_END, () => {
-        this.decreaseIndent();
-      })
-      .on(EVENT_TEST_PASS, test => {
-        // Test#fullTitle() returns the suite name(s)
-        // prepended to the test title
-        console.log(`${this.indent()}pass: ${test.fullTitle()}`);
-      })
-      .on(EVENT_TEST_FAIL, (test, err) => {
-        console.log(
-          `${this.indent()}fail: ${test.fullTitle()} - error: ${err.message}`
-        );
-      })
-      .once(EVENT_RUN_END, () => {
-        console.log(`end: ${stats.passes}/${stats.passes + stats.failures} ok`);
-      });
-  }
-
-  indent() {
-    return Array(this._indents).join('  ');
-  }
-
-  increaseIndent() {
-    this._indents++;
-  }
-
-  decreaseIndent() {
-    this._indents--;
-  }
-}
-
-module.exports = MyReporter;
-```
-
-<!-- AUTO-GENERATED-CONTENT:END -->
+{{ files.simplereporter }}
 
 To use this reporter, execute `mocha --reporter /path/to/my-reporter.js`.
 
@@ -110,4 +47,4 @@ The event names are exported from the `constants` property of `Mocha.Runner`:
 
 **Please use these constants** instead of the event names in your own reporter! This will ensure compatibility with future versions of Mocha.
 
-> It's important to understand that all `Suite` callbacks will be run _before_ the {@link Runner} emits `EVENT_RUN_BEGIN`. Hooks and tests, however, won't run until _after_ the {@link Runner} emits `EVENT_RUN_BEGIN`.
+> It's important to understand that all `Suite` callbacks will be run _before_ the {@link Runner} emits `EVENT_RUN_BEGIN`. Hooks and tests won't run until _after_ the {@link Runner} emits `EVENT_RUN_BEGIN`.

docs/changelogs/README.md

@@ -0,0 +1,7 @@
+# Historical Changelogs
+
+These are changelogs for (very) old versions of Mocha.
+
+These changelogs are _not_ included in the website, and are here only for archival purposes.
+
+_If you're looking for the current changelog, [here is the current changelog](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md)._