docs: validate that the docs can be parsed by mdx

Although our documentation is rendered for the "in the box" docs by
cmark-gfm, the upstream docs site (docs.npmjs.com) uses mdx, which is
a much stricter parser.  Update our docs generator site to ensure that
mdx can parse our documentation as well, to ensure that we get fast
feedback when it would fail.

PR-URL: #2711
Credit: @ethomson
Close: #2711
Reviewed-by: @darcyclarke

docs/dockhand.js

@@ -4,6 +4,7 @@ const path = require('path');
 const fs = require('fs');
 const yaml = require('yaml');
 const cmark = require('cmark-gfm');
+const mdx = require('@mdx-js/mdx');
 const mkdirp = require('mkdirp');
 const jsdom = require('jsdom');
 const npm = require('../lib/npm.js')
@@ -16,25 +17,35 @@ const outputRoot = path.join(docsRoot, 'output');
 
 const template = fs.readFileSync('template.html').toString();
 
-walk(inputRoot);
+const run = async function() {
+    try {
+        await walk(inputRoot);
+    }
+    catch (error) {
+        console.error(error);
+    }
+}
 
-function walk(root, dirRelative) {
+run();
+
+async function walk(root, dirRelative) {
     const dirPath = dirRelative ? path.join(root, dirRelative) : root;
+    const children = fs.readdirSync(dirPath);
 
-    fs.readdirSync(dirPath).forEach((childFilename) => {
+    for (const childFilename of children) {
         const childRelative = dirRelative ? path.join(dirRelative, childFilename) : childFilename;
         const childPath = path.join(root, childRelative);
 
         if (fs.lstatSync(childPath).isDirectory()) {
-            walk(root, childRelative);
+            await walk(root, childRelative);
         }
         else {
-            translate(childRelative);
+            await translate(childRelative);
         }
-    });
+    }
 }
 
-function translate(childPath) {
+async function translate(childPath) {
     const inputPath = path.join(inputRoot, childPath);
 
     if (!inputPath.match(/\.md$/)) {
@@ -70,6 +81,16 @@ function translate(childPath) {
         }
     });
 
+    // Test that mdx can parse this markdown file.  We don't actually
+    // use the output, it's just to ensure that the upstream docs
+    // site (docs.npmjs.com) can parse it when this file gets there.
+    try {
+        await mdx(md, { skipExport: true });
+    }
+    catch (error) {
+        throw new MarkdownError(childPath, error);
+    }
+
     // Inject this data into the template, using a mustache-like
     // replacement scheme.
     const html = template.replace(/\{\{\s*([\w\.]+)\s*\}\}/g, (token, key) => {
@@ -225,3 +246,11 @@ function headerLevel(node) {
 function debug(str) {
     console.log(str);
 }
+
+class MarkdownError extends Error {
+    constructor(file, inner) {
+        super(`failed to parse ${file}`);
+        this.file = file;
+        this.inner = inner;
+    }
+}