diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2021-02-16 21:54:05 +0300 |
---|---|---|
committer | nlf <quitlahok@gmail.com> | 2021-02-18 23:49:29 +0300 |
commit | af4422cdbc110f93203667efc08b16f7aa74ac2f (patch) | |
tree | 98b5e2a13a19c3cfec0bb5ad3c4d9ec4747cf368 /docs | |
parent | 38d87e7c24aea13b0f1c1157aad58d9d15bf8e63 (diff) |
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: https://github.com/npm/cli/pull/2711
Credit: @ethomson
Close: #2711
Reviewed-by: @darcyclarke
Diffstat (limited to 'docs')
-rw-r--r-- | docs/dockhand.js | 43 |
1 files changed, 36 insertions, 7 deletions
diff --git a/docs/dockhand.js b/docs/dockhand.js index 41d01b1cf..ae68e3fbb 100644 --- a/docs/dockhand.js +++ b/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; + } +} |